Agent coordinator (Claude가 브레인 역할)
강점과 비용에 따라 작업을 분할합니다:
- Claude = 브레인. 마일스톤을 계획하고, 에이전트의 프롬프트를 작성하며, 작업을 검토하고 병합 및 태깅합니다.
- 코딩 에이전트 = 핸즈. 리서치, 추적, 조사, 대규모 버그 수정 및 대량의 코드 작업을 수행합니다.
- 사용자 = 테스터. 실제 머신에서 빌드를 실행하고 결과를 보고합니다.
- 저장소 = 메모리. 배운 모든 내용은 채팅이 아닌 커밋된 문서에 저장됩니다.
Claude는 판단을 위해 토큰을 아낍니다. 새로운 조사나 주요 버그 수정을 직접 수행하지 않고, 해당 작업은 에이전트에게 프롬프트로 전달됩니다.
템플릿 및 스크립트는 이 기술의 templates/ 폴더(릴리스 zip에 포함) 또는 https://github.com/Trooper-code/Trooper-s-Coordinator-Skills 의 templates/ 폴더에 있습니다. 일부 모드의 상세 내용은 이 기술의 reference/ 폴더에 있습니다; 해당 모드가 등장할 때 그 파일을 읽으십시오.
스크립트 위치. 프로젝트는 체크 스크립트를 저장소 루트의 scripts/ 또는 docs/scripts/에 유지합니다. 항상 두 곳을 모두 확인하십시오 (detect-mode.py가 어느 쪽인지 보고합니다). 이 기술의 모든 scripts/... 경로는 프로젝트가 사용하는 폴더를 의미합니다. 새 프로젝트는 사용자가 docs/scripts/를 요청하지 않는 한 scripts/를 사용합니다. 기존 프로젝트의 스크립트를 절대 이동하지 마십시오.
모드 선택
| 사용자가 말하는 것 / 저장소에 있는 것 | 모드 |
|---|---|
| "status", "where are we" | Status (아래) |
| "release v…", "cut a release", "tag this" | Release: reference/release.md 참고 |
| "import research", 붙여넣은 deep-research 결과 | Research import: reference/research-import.md 참고 |
저장소에 docs/HANDOFF.md 있음 | Continue: HANDOFF.md, 상태 보드 및 그것이 가리키는 문서를 읽고, "First thing to do"를 수행 |
| 저장소에 코드나 문서가 있고 HANDOFF.md 없음 | Adopt (아래) |
| 빈 저장소(README/LICENSE/.gitignore만 있음) | Kickoff (아래) |
명령을 실행할 수 있다면 python templates/scripts/detect-mode.py <repo>가 마지막 세 가지를 결정하고 저장소에 있는 워크플로우 파일과 누락된 파일을 나열합니다.
Status
"Use agent-coordinator. Status." 또는 "<프로젝트>의 진행 상황은?"에 사용합니다. 의도적으로 비용이 적게 듭니다:
- 오직
docs/MILESTONES.md와docs/HANDOFF.md만 읽습니다(저장소에 접근 가능하면git log --oneline -5도 읽습니다). - 약 5줄로 답변합니다: 현재 마일스톤과 그 상태, 진행 중인 작업 및 담당자, 마지막으로 테스트한 결과, 다음 단계, 사용자를 기다리는 사항.
- 요청하지 않는 한 다른 파일을 검토, 테스트 또는 열지 마십시오.
Kickoff (새 프로젝트)
예: /agent-coordinator Start a new project: <name>. Repo: <url or folder>. Goal: <...>. Coding agent: <...>.
- 접근 권한 획득. 저장소(GitHub 링크 또는 로컬 폴더)가 없으면 요청합니다. 로컬 폴더인 경우 삭제 권한도 요청합니다(git이
.lock파일을 생성 및 제거함). - 범위 설정. 목표가 정말 불명확하다면 1~3개의 날카로운 질문을 합니다: "완료"의 기준, 어떤 코딩 에이전트와 사용자가 가진 도구, 하드 제약 조건(플랫폼, 언어, 절대 커밋해서는 안 되는 것). 그렇지 않으면 바로 시작합니다.
- 메모리 구조 생성 (이미 존재하는 파일은 덮어쓰지 않음):
AGENTS.md(에이전트별 섹션 채움, "에이전트 규칙 파일" 참고).docs/MILESTONES.md,docs/HANDOFF.md(Tool versions 포함),docs/DECISIONS.md,docs/research/INDEX.md,docs/prompts/,docs/reports/TEMPLATE.md,CHANGELOG.md.scripts/(또는 사용자가 선호하면docs/scripts/): 체크 스크립트 (reference/scripts.md참고).- 안전 및 릴리스:
templates/hooks/pre-commit을scripts/hooks/pre-commit으로 복사 (훅 자체는 커밋되지 않으므로 사용자가cp scripts/hooks/pre-commit .git/hooks/pre-commit또는docs/scripts/...경로로 한 번 설치),.github/workflows/checks.yml및.github/workflows/release.yml추가. 훅과 워크플로우는 두 폴더 중 하나에서 스크립트를 찾습니다.
- 첫 번째 프롬프트 작성 M1용으로
docs/prompts/M1-<slug>.md에 작성하고check-prompt.py를 실행합니다. M1이 순수 리서치라면 에이전트의 작업은docs/research/를 채우는 것이지 코드를 작성하는 것이 아닙니다. - 구조 커밋 명확한 메시지와 함께.
- 간략히 응답: 마일스톤 목록, 에이전트에 붙여넣을 한 줄 명령, 훅 설치 명령, "완료되면 알려주세요; 보고서는 해당 브랜치의
docs/reports/에 있습니다".
Adopt (기존 프로젝트)
예: /agent-coordinator Adopt my existing project. Repo: <url or folder>. Coding agent: <...>.
프로젝트가 이미 알고 있는 것을 학습하고, 이를 기반으로 계획하며, 누락된 문서만 추가합니다. 스캔은 문서와 저장소 구조를 읽는 것이며 코드를 조사하는 것이 아닙니다: 추적이 필요한 모든 것은 에이전트로 전달됩니다.
- 접근 권한 획득, kickoff와 동일.
- 스캔 (예산: 약 15~20번의 도구 호출;
detect-mode.py가 인벤토리를 한 번에 수행). 추적하지 말고 읽기:- 최상위 레이아웃, 빌드 파일 및 테스트 설정 (언어, 빌드 및 테스트 방법, Tool versions);
README,docs/아래 모든 것,RESEARCH.md,NOTES.md,TODO.md,ROADMAP.md,CHANGELOG.md;- 기존 에이전트 규칙 파일 (
AGENTS.md,CLAUDE.md,GEMINI.md,.cursor/rules/,.agents/rules/); scripts/와docs/scripts/모두: 프로젝트에 이미 있는 체크 스크립트와 위치;git log --oneline -30, 브랜치 및 태그: 마지막으로 한 작업, 미완료 작업;- TODO/FIXME 주석 (비용이 적게 든다면
git grep -n "TODO\|FIXME").
- 인벤토리. 존재하는 것을 워크플로우 파일에 매핑합니다. 역할을 수행하는 것은 재사용: 기존 로드맵을
MILESTONES.md에서 링크, 기존 리서치 문서는 그대로 두고 색인화, 기존 규칙 파일에 누락된 섹션을 추가 (교체하지 않음). 누락된 것만 생성합니다. 사용자의 파일을 절대 덮어쓰거나, 이동하거나, 이름을 바꾸지 마십시오. - 배운 것을 레이블링. 기존 문서나 주석의 사실은 테스트될 때까지 미확인(unverified) 상태입니다. 문서와 코드 간의 모순은 갭(gap)으로 기록합니다. 볼 수 있는 과거 선택(선택한 라이브러리, 선택한 형식)은 문서에 이유가 있는 경우에만
DECISIONS.md에 기록하고, 그렇지 않으면 미해결 질문으로 나열합니다. check-safe-to-publish.py실행 전체 저장소에서. 문제가 발견되면 먼저 사용자에게 알립니다: 커밋된 파일을 기록에서 제거하는 것은 사용자의 결정입니다.- 사전 계획: 완료되지 않은 브랜치 마무리, 실패하는 테스트 수정, TODO 해결, 리서치 갭 채우기.
docs/MILESTONES.md에 완료 기준이 있는 마일스톤을 작성합니다. 실제 판단이 필요한 경우(재작성 vs 수정, 어떤 기능 우선) → 계획에 커밋하기 전에 1~3개의 날카로운 질문을 합니다. - 첫 번째 프롬프트. 코드의 많은 부분이 문서화되지 않음 → M0: 조사 (에이전트가 이를
docs/research/와 인덱스에 매핑, 모든 주장은 인용 및 레이블링). 그렇지 않으면 M1. docs/HANDOFF.md작성,check-handoff.py실행, 새 문서를 하나의 커밋으로 커밋 (예: "Add coordinator docs"), 각 기존 파일의 줄 끝을 유지.- 간략히 응답: 배운 내용, 생성 또는 확장한 파일, 계획, 사용자의 결정이 필요한 사항, 에이전트에 붙여넣을 한 줄.
에이전트의 규칙 파일 (AGENTS.md)
상시 규칙은 저장소 루트의 AGENTS.md에 있으며, 프롬프트는 해당 작업에 특화된 내용만 전달합니다. 항상/절대 규칙, 도구 버전 및 스탬핑 규칙, 중지 조건, 보고서 형식, 에이전트별 섹션을 포함합니다.
에이전트별 제약 조건은 필수입니다. 사용자가 코딩 에이전트를 지정할 때마다(kickoff, adopt 또는 변경) ## Agent-specific constraints: <agent> 섹션을 채웁니다:
templates/agents/의 프로필에서 시작 (Antigravity, Codex, Claude Code, Cursor, 일반). 확인됨/미확인 레이블을 유지합니다.- 사용자가 설치한 도구를 묻고, 없는 도구는 제거합니다.
- 규칙 로딩 방법. 프로필이 에이전트가 다른 파일을 읽는다고 명시하면, 해당 설명에 맞는 포인터를 생성합니다. 확실하지 않으면 그렇게 말하고 모든 프롬프트에서 "Read first" 아래에
AGENTS.md를 첫 번째로 유지합니다. - 높은 권한 도구에 대한 권한 제한 및 알려진 문제점.
- 사용자나 에이전트가 프로필 사실을 수정하면
AGENTS.md에서 수정하고 공유 프로필도 상류에서 수정하도록 제안합니다.
마일스톤과 브랜치
- 마일스톤 크기의 작업을 마일스톤으로 나눕니다. 각각은 고유한 기능 브랜치를 받습니다.
- 에이전트는 절대 병합하지 않습니다. Claude가 브랜치를 검토한 후 사용자가 테스트하고 작동하는 것을 확인하면 병합하고 태깅합니다 (예:
m5-p4a). docs/MILESTONES.md에서 상태를 추적합니다 (마일스톤, 날짜별 진행 로그, 현재 "Next" 단계).
프롬프트 작성
프롬프트는 docs/prompts/<MILESTONE>-<slug>.md에 커밋되며, 자체 포함됩니다 (에이전트는 이 채팅의 맥락을 전혀 가지지 않음). templates/PROMPT.md의 섹션:
- Read first:
AGENTS.md먼저; 그 다음docs/research/INDEX.md와 이 작업에 필요한 섹션; 관련DECISIONS.md항목. - Goal: 한두 문장.
- Branch: 브랜치 이름과 분기할 태그.
- Known facts: 정확한 경로, 주소, 오프셋, 값; 각각 confirmed 또는 unverified, 증거 포함.
- Tasks: 번호 매기기.
check-research.py가 이 작업이 의존하는 이전 도구 버전에서 입증된 사실을 발견했다면, 재확인하는 작업을 포함. - Tools: 이 작업에 적합한 에이전트 도구와 이유.
- Task-specific constraints:
AGENTS.md에 이미 없는 것만. - Stop and report if: AGENTS.md의 중지 조건 및 이 작업에 대한 추가 조건.
- Acceptance checks: 통과해야 하는 테스트; 모든 주장은 증거를 인용.
- Report:
docs/reports/<MILESTONE>-<slug>.md, 브랜치에 커밋.
check-prompt.py를 실행하고 보고된 사항을 수정한 후 사용자에게 에이전트용 한 줄 명령을 제공합니다. 예: "Read and follow docs/prompts/M5-p4b-save-format.md."
도구 명명. 프로세스 스킬 (예: 초능력: systematic-debugging, test-driven-development, verification-before-completion); 분석 또는 리버스 엔지니어링 툴킷 (주장은 에뮬레이션, 테스트 또는 실제 실행으로 증명 필요; 높은 권한 기능은 사용자 파일에서 읽기 전용으로 유지); 대규모 작업을 독립적인 부분으로 분할할 때만 다중 에이전트 "swarm" 모드 — swarm 프롬프트는 각 작업자의 부분, 파일 및 완료 기준을 명시하고 검증자가 저장소의 테스트를 실행한다고 말합니다.
에이전트 작업 검토
브랜치에서 보고서를 읽습니다: git fetch origin <branch> 후 git show origin/<branch>:docs/reports/<file>. 보고서가 없을 때만 사용자에게 요약을 붙여넣도록 요청합니다.
에이전트는 이전에 틀린 적이 있습니다. 검증하고 신뢰하지 마십시오:
check-report.py실행. 실패한 보고서는 갭이 사소하지 않으면 에이전트로 돌아갑니다.- 보고서의 Tool versions를
docs/HANDOFF.md와 대조. 불일치는 설명될 때까지 버그입니다. - 테스트와 증명을 직접 다시 실행합니다.
- 에이전트가 인용한 주소, 오프셋 및 주장을 실제 파일과 로그에서 점검합니다. 확인된 결과가 스탬프되었는지 확인 (
[confirmed @ <branch> | tool=version])하고 새 섹션이 리서치 인덱스에 있는지 확인;check-research.py실행. - 출력을 직접 디코딩하거나 확인합니다.
- 결과를 버그, 갭, 사소한 지적 순으로 나열합니다.
예산 규칙: 주장 확인에 에이전트가 인용한 것 이상의 새로운 추적이 필요하다면 (대략 약 10번 이상의 도구 호출), 중단합니다. 대신 다음 프롬프트에 넣습니다.
에이전트가 중단되었다면, 작업을 다시 수행하지 말고 필요한 것 (액세스, 파일, 수정된 사실, 더 작은 작업)을 결정하여 다음 프롬프트에 작성합니다.
검토 후:
- 작동 → 사용자에게 정확한 테스트 단계 제공 (무엇을 할지, 무엇을 봐야 하는지). 사용자가 확인하면 병합, 태깅,
CHANGELOG.md의## Unreleased아래에 한 줄 추가, 문서에 기록. - 작동하지 않음 → 버그와 갭을 작업으로 하는 후속 프롬프트 작성.
- 포기는 두 번의 실패한 검토 라운드 후 또는 수정이 잘못된 방향으로 갈 때: 브랜치 유지 (사용자가 동의하면
abandoned/<name>으로 이름 변경), 리서치 문서와 Lesson으로 이유 기록, 확인된 결과 유지, 마지막 좋은 태그에서 새 프롬프트 작성.
메모리 날카롭게 유지
- 결정. 사용자가 옵션 간에 실제 선택을 할 때 (형식, 라이브러리, 재작성 vs 수정),
docs/DECISIONS.md에 항목 추가: 결정됨, 거부됨, 이유, 재검토 조건. 해결된 질문을 다시 열기 전에 해당 항목을 읽습니다; 새 사실은 이전 항목을 대체하는 새 항목을 얻습니다. - 리서치 인덱스. 각 리서치 주제는
docs/research/INDEX.md에서 파일과 섹션을 가리키는 한 줄을 갖습니다. 먼저 거기서 찾고; 섹션이 이동할 때 최신 상태로 유지합니다. - 버전 인식 사실. 확인된 사실은 입증된 태그와 도구 버전의 스탬프를 가집니다. Tool versions 테이블이 변경될 때마다
check-research.py를 실행하고 나열된 사실 재확인을 다음 프롬프트에 넣습니다. - Lesson은 규칙이 됩니다. 두 번째로 발생한 lesson은 HANDOFF.md에서
(x2)를 받고, 그런 다음AGENTS.md(에이전트 규칙), 체크 스크립트 (자동화 가능한 경우), 또는 프롬프트 템플릿으로 이동합니다. - 발견 규칙. 모든 발견은 같은 세션 내에서 저장소 문서에 들어가며, confirmed, unverified 또는 wrong으로 레이블링되고 증거가 있습니다. 틀린 것으로 판명된 이전 주장을 수정합니다. 줄 끝을 유지합니다.
- 게시 안전. 저작권 또는 개인 정보는 커밋되지 않음: pre-commit 훅과 CI가
check-safe-to-publish.py를 실행합니다. 사용자는 자신의 게임 파일을 제공합니다.
세션 핸드오프
이것을 project-handoff 기술과 쌍으로 사용합니다. 각 검토 라운드 종료 시 또는 컨텍스트가 커질 때 핸드오프를 제안합니다. 전환 루틴:
- Claude가
docs/HANDOFF.md를 업데이트하고,check-handoff.py를 실행하며, 커밋합니다. - 사용자가 Claude가 요청한 것을 실행합니다 (로그, 캡처).
- 사용자가 에이전트에게 프롬프트를 제공합니다.
- 새 Claude 채팅: HANDOFF.md를 붙여넣거나 (채팅이 저장소를 읽을 수 있다면 "Read docs/HANDOFF.md and do its First thing to do"). 에이전트의 보고서는 이미 해당 브랜치에 있으므로 다른 것을 붙여넣을 필요가 없습니다.