Tamandua

이미 사용 중인 코딩 어시스턴트 — Claude Code, Copilot, Codex, 로컬 모델 — 를 SWAT+에서 더 저렴하고 더 정확하게 만듭니다.

이것은 어시스턴트가 아닙니다. 정적 분석만으로 SWAT+ Fortran 소스의 facts 전용 인덱스를 구축하고, 이를 MCP 도구와 작업 트리 안의 파일로 제공합니다. 위치가 포함된 프로시저, 호출 그래프, 유닛 번호가 있는 파일 I/O, 필드 경로별 변수 쓰기, 인덱스 변수가 포함된 루프 헤더, 단위와 의미가 소스에 인라인으로 문서화된 파생 형식. 그 안에 모델이 작성한 것은 없습니다.

왜 신경 써야 하는가: hru_control의 루프를 나열하라는 요청을 받은 어시스턴트는 원시 소스를 읽고 890줄 전체를 훑은 뒤 21개 중 18개라는 깔끔한 표를 만들어 냈습니다. 답변 어디에도 불완전하다는 암시는 없었습니다. 여기서는 모든 것을 요구하는 질문이 구조적으로 완전하게 답해지며, 모든 행에는 해당 파일과 줄 번호가 실려 있습니다.

• 현재 상태: docs/status.md ← 여기서 시작

• 결정 사항: docs/decisions.md

• 의존성 고정: docs/pins.toml

사용하기

도구만 원한다면 — SWAT+ 체크아웃이나 파서는 필요 없습니다:

pip install "git+https://github.com/tugraskan/Tamandua.git@v0.1.1"

태그된 패키지에는 고정된 SWAT+ facts 스냅샷이 포함되어 있습니다. 향후 PyPI 배포 이름은 swatplus-tamandua입니다 (tamandua는 이미 관련 없는 프로젝트가 소유하고 있습니다). 머신별 경로 없이 어시스턴트를 서버에 연결하세요:

// .mcp.json (Claude Code) — VS Code uses .vscode/mcp.json, where these
// entries nest inside a top-level "servers" object instead.
{
  "mcpServers": {
    "swatplus-source": {
      "command": "swatplus-mcp",
      "args": ["--compact"]
    }
  }
}

SWAT+ 체크아웃과 파서가 있다면, 서버를 소스에 직접 연결하세요:

swatplus-mcp --source /path/to/swatplus --compact

실행 중인 프로세스는 각 요청 전에 작업 중인 Fortran 트리의 지문을 계산합니다. 편집 후에만 다시 파싱하므로, 수동으로 다시 빌드하거나 서버를 재시작하지 않아도 다음 답변이 소스를 따릅니다.

다른 사람을 위한 이식 가능한 facts 파일을 만들려면:

cd <your swatplus checkout> && swatplus-build

이 명령은 swatplus-facts.json만 작성하고 그 외에는 아무것도 하지 않습니다. --facts로 시작된 서버는 해당 파일이 교체되면 이를 감지하고, 재시작 없이 가장 최신의 완전한 스냅샷을 다시 로드합니다. 패키지에 번들된 릴리스 스냅샷은 설계상 정적으로 유지됩니다.

도구가 MCP 서버를 실행할 수 없다면, swatplus-build --markdown은 SWATPLUS_INDEX.md도 렌더링하고 모든 어시스턴트 지침 파일(CLAUDE.md, AGENTS.md, .github/copilot-instructions.md)이 그 파일을 가리키게 하여, 대신 grep으로 검색할 수 있게 합니다. 이것은 대체 수단이지 기본값이 아닙니다.

이 검사는 마지막 커밋이 아니라 작업 트리를 해시합니다. 질문은 편집 중인 코드에 대해 나오며, 커밋 기반 검사가 낡은 인덱스를 최신이라고 판단하는 시점이 바로 그때입니다.

Related MCP server: fw-context-mcp

dataselector와 함께 사용

swatplus-dataselector는 나머지 절반을 담당합니다: 입력 파일의 열이 무엇을 의미하는지, 그리고 실제 TxtInOut 데이터셋에 무엇이 들어 있는지. 둘은 겹치지 않습니다 — 이쪽은 Fortran이 무엇을 하는지 알고, 저쪽은 파일이 무엇을 담고 있는지 압니다. 둘 다 실행하고 어시스턴트에게 어느 것이 어떤 용도인지 알려주세요.

구조

tamandua/
├── index/             # build the facts, render, install pointers, snapshot
│   ├── build.py       #   static analysis -> SourceIndex
│   ├── snapshot.py    #   read/write swatplus-facts.json, so serving needs no parser
│   ├── render.py      #   SOURCE_INDEX.md
│   ├── install.py     #   assistant instruction-file pointers
│   └── scope.py       #   loop nesting, for conditional breakpoints
├── mcp/server.py      # 14 read-only tools over the same objects
├── mcp/client.py      # generic MCP stdio client (talk to another server)
├── output/reader.py   # query a run's output files
└── config.py          # loads docs/pins.toml

개발

export SWATPLUS_SOURCE=/path/to/swatplus
export SWATPLUS_REFERENCE_CORPUS=/path/to/swatplus-reference-corpus  # the parser
python -m pip install -e ".[dev]"
pytest                       # 151 pass, 9 skipped (128/32 without the parser)

파서는 빌드 타임 의존성일 뿐입니다. 번들된 facts 파일 덕분에 설치된 서버는 파서도 SWAT+ 소스도 없이 실행될 수 있습니다 (D-8 참조). 다른 스냅샷을 사용하려면 --facts를, 체크아웃에서 실시간으로 빌드하려면 --source를 전달하세요.

# build the publishable artifacts
swatplus-build --facts dist/swatplus-facts.json --out dist/SWATPLUS_INDEX.md

# serve them with nothing else installed
swatplus-mcp --facts dist/swatplus-facts.json

v*.*.* 태그를 달면 .github/workflows/release.yml이 실행됩니다. 이 워크플로는 고정된 커밋을 기준으로 둘 다 빌드하고, 체크아웃을 삭제하고, 스냅샷이 여전히 응답하는지 검증한 후 게시합니다.

원칙

Facts만 — 모델이 작성한 것은 인덱스에 들어가지 않습니다. 모든 주장에는 파일과 줄 번호가 포함됩니다. 결론을 내리기 전에 측정하세요. 발견 사항은 이를 생성한 스크립트와 함께 docs/*_experiment.md에 있습니다. 이 작업에서 결함 8개는 일상적인 사용으로 발견되었고 어떤 테스트 하네스로도 발견되지 않았으므로, 그것에 대해 추론하기보다 실제로 실행하는 쪽을 택하세요.