Community코딩 & 개발github.com

agent-coordinator

Claude를 브레인으로, 별도의 코딩 에이전트(예: Antigravity/Gemini, Codex, 다른 Claude)를 핸즈로 사용하여 프로젝트를 설계, 검토 및 관리하는 기술입니다.

agent-coordinator란 무엇인가요?

이 기술은 강점과 비용에 따라 작업을 분할하는 워크플로우를 제공합니다. Claude는 마일스톤을 계획하고, 에이전트 프롬프트를 작성하며, 작업을 검토하고 병합 및 태깅하는 '브레인' 역할을 합니다. 코딩 에이전트는 리서치, 대규모 버그 수정, 코드 조사 등 '핸즈' 작업을 수행하며, 사용자는 실제 머신에서 빌드를 테스트합니다. 모든 지식은 채팅이 아닌 저장소 문서에 보관됩니다. 이 기술은 새 프로젝트 시작(kickoff), 기존 프로젝트 채택(adopt), 리서치 결과 가져오기, 릴리스 생성, 프로젝트 상태 확인 등 다양한 모드를 지원하며, Claude Code, Cursor, Codex 등 여러 플랫폼에서 사용 가능합니다. 주요 구성 요소로는 `docs/MILESTONES.md`, `docs/HANDOFF.md`, `AGENTS.md` 등이 있으며, 스크립트는 `scripts/` 또는 `docs/scripts/` 폴더에 위치합니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/Trooper-code/Trooper-s-Coordinator-Skills/tree/HEAD/skills/agent-coordinator

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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: <...>.

  1. 접근 권한 획득. 저장소(GitHub 링크 또는 로컬 폴더)가 없으면 요청합니다. 로컬 폴더인 경우 삭제 권한도 요청합니다(git이 .lock 파일을 생성 및 제거함).
  2. 범위 설정. 목표가 정말 불명확하다면 1~3개의 날카로운 질문을 합니다: "완료"의 기준, 어떤 코딩 에이전트와 사용자가 가진 도구, 하드 제약 조건(플랫폼, 언어, 절대 커밋해서는 안 되는 것). 그렇지 않으면 바로 시작합니다.
  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 추가. 훅과 워크플로우는 두 폴더 중 하나에서 스크립트를 찾습니다.
  4. 첫 번째 프롬프트 작성 M1용으로 docs/prompts/M1-<slug>.md에 작성하고 check-prompt.py를 실행합니다. M1이 순수 리서치라면 에이전트의 작업은 docs/research/를 채우는 것이지 코드를 작성하는 것이 아닙니다.
  5. 구조 커밋 명확한 메시지와 함께.
  6. 간략히 응답: 마일스톤 목록, 에이전트에 붙여넣을 한 줄 명령, 훅 설치 명령, "완료되면 알려주세요; 보고서는 해당 브랜치의 docs/reports/에 있습니다".

Adopt (기존 프로젝트)

예: /agent-coordinator Adopt my existing project. Repo: <url or folder>. Coding agent: <...>.

프로젝트가 이미 알고 있는 것을 학습하고, 이를 기반으로 계획하며, 누락된 문서만 추가합니다. 스캔은 문서와 저장소 구조를 읽는 것이며 코드를 조사하는 것이 아닙니다: 추적이 필요한 모든 것은 에이전트로 전달됩니다.

  1. 접근 권한 획득, kickoff와 동일.
  2. 스캔 (예산: 약 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").
  3. 인벤토리. 존재하는 것을 워크플로우 파일에 매핑합니다. 역할을 수행하는 것은 재사용: 기존 로드맵을 MILESTONES.md에서 링크, 기존 리서치 문서는 그대로 두고 색인화, 기존 규칙 파일에 누락된 섹션을 추가 (교체하지 않음). 누락된 것만 생성합니다. 사용자의 파일을 절대 덮어쓰거나, 이동하거나, 이름을 바꾸지 마십시오.
  4. 배운 것을 레이블링. 기존 문서나 주석의 사실은 테스트될 때까지 미확인(unverified) 상태입니다. 문서와 코드 간의 모순은 갭(gap)으로 기록합니다. 볼 수 있는 과거 선택(선택한 라이브러리, 선택한 형식)은 문서에 이유가 있는 경우에만 DECISIONS.md에 기록하고, 그렇지 않으면 미해결 질문으로 나열합니다.
  5. check-safe-to-publish.py 실행 전체 저장소에서. 문제가 발견되면 먼저 사용자에게 알립니다: 커밋된 파일을 기록에서 제거하는 것은 사용자의 결정입니다.
  6. 사전 계획: 완료되지 않은 브랜치 마무리, 실패하는 테스트 수정, TODO 해결, 리서치 갭 채우기. docs/MILESTONES.md에 완료 기준이 있는 마일스톤을 작성합니다. 실제 판단이 필요한 경우(재작성 vs 수정, 어떤 기능 우선) → 계획에 커밋하기 전에 1~3개의 날카로운 질문을 합니다.
  7. 첫 번째 프롬프트. 코드의 많은 부분이 문서화되지 않음 → M0: 조사 (에이전트가 이를 docs/research/와 인덱스에 매핑, 모든 주장은 인용 및 레이블링). 그렇지 않으면 M1.
  8. docs/HANDOFF.md 작성, check-handoff.py 실행, 새 문서를 하나의 커밋으로 커밋 (예: "Add coordinator docs"), 각 기존 파일의 줄 끝을 유지.
  9. 간략히 응답: 배운 내용, 생성 또는 확장한 파일, 계획, 사용자의 결정이 필요한 사항, 에이전트에 붙여넣을 한 줄.

에이전트의 규칙 파일 (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의 섹션:

  1. Read first: AGENTS.md 먼저; 그 다음 docs/research/INDEX.md와 이 작업에 필요한 섹션; 관련 DECISIONS.md 항목.
  2. Goal: 한두 문장.
  3. Branch: 브랜치 이름과 분기할 태그.
  4. Known facts: 정확한 경로, 주소, 오프셋, 값; 각각 confirmed 또는 unverified, 증거 포함.
  5. Tasks: 번호 매기기. check-research.py가 이 작업이 의존하는 이전 도구 버전에서 입증된 사실을 발견했다면, 재확인하는 작업을 포함.
  6. Tools: 이 작업에 적합한 에이전트 도구와 이유.
  7. Task-specific constraints: AGENTS.md에 이미 없는 것만.
  8. Stop and report if: AGENTS.md의 중지 조건 및 이 작업에 대한 추가 조건.
  9. Acceptance checks: 통과해야 하는 테스트; 모든 주장은 증거를 인용.
  10. 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>. 보고서가 없을 때만 사용자에게 요약을 붙여넣도록 요청합니다.

에이전트는 이전에 틀린 적이 있습니다. 검증하고 신뢰하지 마십시오:

  1. check-report.py 실행. 실패한 보고서는 갭이 사소하지 않으면 에이전트로 돌아갑니다.
  2. 보고서의 Tool versions를 docs/HANDOFF.md와 대조. 불일치는 설명될 때까지 버그입니다.
  3. 테스트와 증명을 직접 다시 실행합니다.
  4. 에이전트가 인용한 주소, 오프셋 및 주장을 실제 파일과 로그에서 점검합니다. 확인된 결과가 스탬프되었는지 확인 ([confirmed @ <branch> | tool=version])하고 새 섹션이 리서치 인덱스에 있는지 확인; check-research.py 실행.
  5. 출력을 직접 디코딩하거나 확인합니다.
  6. 결과를 버그, 갭, 사소한 지적 순으로 나열합니다.

예산 규칙: 주장 확인에 에이전트가 인용한 것 이상의 새로운 추적이 필요하다면 (대략 약 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 기술과 쌍으로 사용합니다. 각 검토 라운드 종료 시 또는 컨텍스트가 커질 때 핸드오프를 제안합니다. 전환 루틴:

  1. Claude가 docs/HANDOFF.md를 업데이트하고, check-handoff.py를 실행하며, 커밋합니다.
  2. 사용자가 Claude가 요청한 것을 실행합니다 (로그, 캡처).
  3. 사용자가 에이전트에게 프롬프트를 제공합니다.
  4. 새 Claude 채팅: HANDOFF.md를 붙여넣거나 (채팅이 저장소를 읽을 수 있다면 "Read docs/HANDOFF.md and do its First thing to do"). 에이전트의 보고서는 이미 해당 브랜치에 있으므로 다른 것을 붙여넣을 필요가 없습니다.

관련 스킬