project-agents-public

대규모 서비스 개발(풀스택·차세대 등)을 단계(stage) × 업무(slice) × 계층(layer) 으로 쪼개어 에이전트가 선형 파이프라인으로 수행하고, 검증 단계에서 나온 결함을 리팩토링 요구서로 되먹임하여 반복할수록 완성도가 높아지도록 설계한 Claude Code repo입니다.

0 준비 ─> 1 업무분류 ─> 2 Backend ─> 3 공통화 ─> 4 Frontend ─> 5 통합테스트 ─> 6 보안 ─> 7 QA ─> 8 산출물 ─> 9 납품 패키징
                ^                                                  │           │        │
                └──────────────── 리팩토링 요구서 (refactor-requests) <──────────┴────────┘

단계 개요

• 1~4단계는 slice 단위로 반복하고, 5~7단계에서 나온 요구서는 target_stage/target_layer가 지정되어 해당 단계·계층만 다시 돈다 (무조건 1단계부터 되돌아가지 않음).
• 각 단계는 developer 에이전트 → reviewer 에이전트 순으로 실행되며, 게이트(빌드·테스트)를 통과해야 다음 단계로 넘어간다.
• 게이트 통과는 문장이 아니라 증거로 판정한다. 레포트 끝의 pa-meta 블록(실행 명령·종료 코드·테스트 개수·git HEAD·확인 필요 항목)을 python tools/gate.py check --stage [--slice ] 가 실제 git·파일과 대조한다 (templates/report-meta.md).
• 결함은 리팩토링 요구서(RR), 아직 확인되지 않은 것은 확인 필요 항목(open-items.yaml)으로 남아 다음 단계가 닫는다.
• 단계를 늘려도 같은 축에서만 검증하면 새 결함은 나오지 않는다. 1단계가 slice 마다 traits 를 정하고, 그것이 요구하는 검증 축(unit·module·real-db·real-server·browser·concurrency·security-static)이 닫혔는지를 gate.py 가 대조한다 (pipeline-core §14).
• /run 은 게이트 판정으로 다음 단계를 자동 진행하고, 사람 승인 지점·FAIL 에서만 멈춘다.
• 토큰 위생 (pipeline-core §26): 비용의 대부분은 캐시 읽기(매 호출마다 쌓인 문맥 전체를 다시 읽는 양의 합)다. 그래서 지침은 핵심 + 필요한 절만 읽고, 긴 Bash 출력은 훅이 로그 파일로 빼 요약만 보이며, 서브에이전트 보고는 산문 3000자 이내 + 상세 레포트 파일, 결과 블록은 훅이 reports/agent-results/ 에 저장해 ingest_result.py 가 그대로 옮기고, 마무리 검사는 gate.py finalize 가 문제만 출력한다. 효과는 python tools/cost_probe.py 경로> --out 로 실측한다. .claude/settings.json 에 자동 압축 기준(autoCompactWindow: 400000)과 서브에이전트 캐시 1시간(subagentPromptCacheTtl: "1h")을 둔다.
• 핵심 원칙은 지침만이 아니라 훅이 도구 호출 시점에 강제한다(.claude/settings.json): 게이트를 통과하지 못한 단계를 done 으로