Harness Bootstrap
저장소를 어떤 개발자 머신에서든 새 에이전트 세션이 저장소만으로 다섯 가지 질문(무엇인지, 어떻게 구성되었는지, 어떻게 실행하는지, 어떻게 검증하는지, 어디서 멈췄는지)에 답할 수 있는 곳으로 만듭니다. 그런 다음 "완료"를 에이전트가 아닌 스크립트가 결정하도록 합니다.
이 스킬은 저장소당 한 번 실행됩니다. 팀이 커밋하는 계약과 라이프사이클 스킬(harness-start, harness-handoff, harness-cleanup, harness-evaluate)을 저장소 내부에 설치하여 모든 팀원이 어떤 코딩 에이전트를 사용하든 클론 시 사용할 수 있게 합니다.
이 파일(scripts/, references/, assets/)의 경로는 이 SKILL.md가 포함된 디렉터리를 기준으로 합니다. 해당 디렉터리는 에이전트와 스킬이 설치된 방식에 따라 달라지므로, 이 파일을 로드한 위치에서 확인하세요. ~/.claude/skills/와 같은 고정 경로를 가정하지 마세요.
어떤 아티팩트의 이유(예: 사용자에게 설명하거나 비정상적인 저장소에 적용하기 위해)가 필요하면 references/principles.md를 읽으세요.
설치하는 모델
| 계층 | 위치 | 커밋됨? | 목적 |
|---|---|---|---|
| 진입 파일 | CLAUDE.md 및/또는 AGENTS.md | 예 | 짧은 맵: 무엇인지, 실행 방법, 검증 방법, 엄격한 규칙, 링크 |
| 문서 | docs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/ | 예 | 에이전트가 코드에서 추론할 수 없는 지식 |
| 계약 | harness/ (설정, 규칙, 체크리스트, 루브릭, 품질 문서, 템플릿, README) | 예 | 모든 사람이 동일한 규칙, PR로만 변경 |
| 검증 | scripts/harness/ | 예 | init.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh |
| 라이프사이클 | .agents/skills/harness-*, 다른 폴더를 읽는 에이전트를 위해 미러링됨 | 예 | 시작, 핸드오프, 정리, 평가 |
| 어댑터 | 에이전트별, 예: Claude Code의 .claude/agents/, .claude/hooks/ | 예 | 선택적 추가 기능: 하위 에이전트, 훅 |
| 작업 상태 | .harness/tasks/<TASK-ID>/ | 아니요 | 기능 목록, 계약, 진행, 핸드오프, 하나의 작업에 대한 실행 로그 |
작업 상태는 매 세션마다 변경되고 한 사람의 브랜치에 속하므로 로컬로 유지됩니다. 커밋하면 병합 충돌이 발생하고 한 개발자의 오래된 상태가 다른 개발자의 에이전트를 오도할 수 있습니다. 이는 캐시입니다. 모든 내구성 있는 것은 작업이 끝나기 전에 코드, 테스트, 문서, PR 또는 이슈 트래커로 승격됩니다. harness/README.md가 이 내용을 팀에 설명합니다.
워크플로
1. 대상 확인
사용자가 의도한 디렉터리에서 git rev-parse --show-toplevel을 실행하세요. Git 저장소가 아니라면 중지하고 그 이유를 말하세요: 워크트리 격리와 베이스 브랜치 검사는 git에 의존합니다. 작업 트리가 더티한지 확인하고, 자체 브랜치에서 부트스트랩을 수행하여 하나의 PR로 검토될 수 있도록 제안하세요.
2. 이미 존재하는 항목 인벤토리
쓰기 전에 먼저 살펴보세요. 다음을 찾아 읽으세요:
- 명령 파일:
AGENTS.md,CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md,GEMINI.md,.cursorrules,.cursor/rules/,.github/copilot-instructions.md,.windsurfrules - 문서:
README*,docs/, ADR 폴더,CONTRIBUTING* - 기존 하네스 조각:
feature_list.json,progress.md,init.sh,Makefile,harness/,scripts/harness/,.harness/ - 에이전트 설정 및 스킬:
.agents/skills/,.claude/(settings.json,skills/,agents/,hooks/),.devin/,.cursor/,.github/,.worktreeinclude .gitignore
기존 콘텐츠가 우선입니다. 확장하되, 팀이 작성한 파일을 묻지 않고 절대 교체하지 마세요.
3. 프로젝트 실행 방식 발견
references/discovery.md를 따르세요. 목표는 각 검증 계층에 대한 명령어의 검증된 목록이며, 각 명령어는 발견한 위치(CI 구성이 가장 강력한 증거입니다. 팀이 실제로 신뢰하는 것이기 때문입니다)와 함께여야 합니다. 또한 코드의 계층 또는 모듈과 그들 간의 의존성 방향을 식별하세요. 이것들이 아키텍처 규칙이 됩니다.
4. 간격에 대해서만 질문
환경에 구조화된 질문 호출이 있다면 저장소에서 답할 수 없었던 질문을 하나의 구조화된 질문 호출로, 그렇지 않으면 단일 메시지로 묶으세요. 일반적인 간격:
- 추론했지만 확실하지 않은 아키텍처 경계("
ui/가db/를 가져올 수 있나요?") - 엔드투엔드 또는 스모크 명령어(존재하지 않는 경우)
- 문서화되지 않은 경우 베이스 브랜치 및 브랜치 명명 규칙
- 팀이 사용하는 코딩 에이전트(Claude Code, Codex, Cursor, Copilot, Devin, Pi 등). 진입 파일과 설치할 에이전트 어댑터를 결정합니다.
- 팀이 Claude Code를 사용하는 경우: 훅 설치 여부(권장됨; 세션 시작 시 작업 상태를 표시하고 작업 상태에 대한 수동 편집을 차단함)
관례적인 기본값이 있는 것은 묻지 말고, 선택한 후 최종 보고서에서 언급하세요.
5. 스캐폴드 복사
bash <이 스킬의 디렉터리>/scripts/install.sh <repo-root> --agents <ids>
--agents는 4단계의 팀 에이전트를 쉼표로 구분된 ID로 받습니다. npx skills CLI가 사용하는 것과 동일한 ID입니다(claude-code, codex, cursor, github-copilot, gemini-cli, opencode, pi, devin, windsurf, kiro-cli, ...; --help에 목록이 있습니다).
스크립트는 assets/project/를 저장소로 복사합니다. 여기에는 대부분의 에이전트가 직접 읽는 .agents/skills/의 라이프사이클 스킬이 포함됩니다. 다른 폴더를 읽는 에이전트(claude-code, devin, windsurf, kiro-cli)의 경우 해당 스킬에 대한 상대 심볼릭 링크를 추가하고, assets/adapters/<id>/에 어댑터가 있는 에이전트의 경우 어댑터 파일을 복사합니다. 심볼릭 링크를 지원하지 않는 Windows 체크아웃이 있는 팀의 경우 --copy를 전달하세요. 그러면 init.sh가 차이가 발생한 복사본을 보고합니다. 스크립트는 절대 기존 경로를 덮어쓰지 않으며, 스크립트를 실행 가능으로 표시하고 경로당 CREATED / LINKED / SKIPPED를 출력합니다. 저장소에 이미 하네스 조각이 있는 경우 먼저 --dry-run을 사용하세요. 모든 SKIPPED 경로에 대해 기존 파일을 읽고 누락된 아이디어를 템플릿을 강제하는 대신 수동으로 병합하세요.
스크립트가 FAILED 경로를 보고하면 에이전트의 샌드박스가 .agents/ 또는 .claude/와 같은 폴더를 보호하고 있을 수 있습니다(Codex는 기본적으로 .agents/에 대해 이렇게 합니다). 환경이 제공하는 권한으로 동일한 명령을 다시 실행하거나 사용자에게 실행을 요청하세요. 절대 스킬을 다른 폴더로 옮기지 마세요: 에이전트는 자신이 읽는 폴더에서만 스킬을 발견하므로, 옮겨진 스킬은 조용히 작동을 멈춥니다.
6. 프로젝트 구체 사항 작성
스캐폴드가 알 수 없는 모든 것은 여러분이 2-4단계에서 읽은 내용을 바탕으로 작성해야 합니다:
harness/config.sh: 각 계층(setup, static, test, smoke, e2e)당 한 줄에 하나의 명령어, 베이스 브랜치, 스택의 디버그 패턴. 계층이 실제로 존재하지 않는 경우에만 비워 두세요.verify.sh는 빈 필수 계층을 통과 대신 UNVERIFIED로 보고합니다. 다른 계층이 이미 실행하는 명령어로 계층을 채우지 마세요(예: 통합 테스트를 "e2e"로). 각 계층은 다른 계층이 제공하지 않는 증거를 추가해야 합니다.references/discovery.md를 참조하세요.harness/architecture-rules.json: 경계당 하나의 규칙,references/architecture-rules.md를 따름. 모든 규칙에는 에이전트를 위해 작성된why와fix가 필요합니다. 오류 메시지가 피드백 루프이기 때문입니다.- 문서: 저장소에 해당하는 문서가 없는 경우에만
docs/ARCHITECTURE.md,docs/PRODUCT.md,docs/RELIABILITY.md를 생성하고,assets/docs-skeletons/에서 시작합니다. 읽은 코드로 작성하고, 각 문서를 ~150줄 미만으로 유지하며, 확인할 수 없는 것은 추측하지 말고TODO(confirm): ...로 표시하세요. 다른 곳에 해당하는 문서가 있으면 복제하지 말고 링크하세요. - 결정 기록: 스캐폴드는
docs/decisions/를 추가합니다. 저장소가 이미 다른 곳(doc/adr/,docs/adr/)에 ADR을 보관하고 있다면 새 폴더를 제거하고harness/README.md, 핸드오프 및 정리 스킬, 템플릿이 기존 위치를 가리키도록 하세요. harness/quality-document.md: 실제 모듈을 정직한 초기 등급 또는 증거가 없는 경우unknown으로 나열하세요. 절대 느낌으로 등급을 매기지 마세요.
7. 진입 파일 연결
assets/snippets/entry-section.md의 섹션을 진입 파일에 삽입하세요. 상단 또는 하단 근처(모델은 긴 파일의 가장자리를 중간보다 더 잘 기억합니다). 진입 파일을 라우터로 유지하세요: ~200줄을 넘으면 세부 사항을 docs/로 옮기고 링크하세요.
AGENTS.md는 표준 진입 파일입니다: 대부분의 코딩 에이전트가 직접 읽습니다. 다른 에이전트는 얇은 포인터를 받고 규칙의 두 번째 복사본은 절대 받지 않으므로 파일이 서로 달라질 수 없습니다.
| 상황 | 이렇게 하세요 |
|---|---|
AGENTS.md와 CLAUDE.md 모두 없음 | 학습한 내용과 섹션을 추가하여 AGENTS.md를 생성합니다. |
AGENTS.md만 있음 | AGENTS.md에 섹션을 추가합니다. |
CLAUDE.md만 있고 팀이 Claude Code만 사용함 | CLAUDE.md에 섹션을 추가합니다. |
CLAUDE.md만 있고 팀이 다른 에이전트도 사용함 | 이동하기 전에 물어보세요: 콘텐츠를 AGENTS.md로 옮기고 CLAUDE.md에 @AGENTS.md를 남겨두는 것을 제안하세요. 팀이 거절하면 CLAUDE.md에 섹션을 추가하고 AGENTS.md를 섹션과 CLAUDE.md에 대한 링크로 생성합니다. |
| 둘 다 있음 | AGENTS.md에 섹션을 추가하고 CLAUDE.md가 @AGENTS.md를 가져오는지 확인하세요. |
그런 다음 기본적으로 AGENTS.md를 읽지 않는 팀이 사용하는 각 에이전트에 대한 포인터를 추가하세요:
| 에이전트 | 포인터 |
|---|---|
| Claude Code | @AGENTS.md를 포함하는 CLAUDE.md. 기본적으로 Claude Code는 CLAUDE.md 또는 CLAUDE.local.md가 없을 때만 AGENTS.md를 읽으므로, import 없이 두 파일이 모두 있는 저장소는 조용히 AGENTS.md를 드롭합니다. |
| Gemini CLI | @AGENTS.md를 포함하는 GEMINI.md 또는 .gemini/settings.json의 "contextFileName": "AGENTS.md". |
이미 저장소에 자체 규칙 파일(.github/copilot-instructions.md, .cursor/rules/, .windsurfrules)이 있는 에이전트 | 해당 파일에 AGENTS.md를 읽으라고 명시하는 한 줄. |
확실하지 않은 에이전트의 현재 동작은 추측하지 말고 자체 문서에서 확인하세요. 에이전트가 읽는 파일은 변경됩니다.
8. 설정 병합
.gitignore:assets/snippets/gitignore.txt에서 누락된 줄을 추가하세요.- Claude Code 전용,
.claude/settings.json:assets/adapters/claude-code/settings-hooks.json의 훅을 병합하세요. 기존 파일을 읽고, 기존hooks.SessionStart/hooks.PreToolUse배열을 교체하지 않고 추가하고, JSON이 유효하도록 유지하세요. 팀이 훅을 거절했다면 이 단계를 건너뛰고 어댑터가 복사한.claude/hooks/를 삭제하세요. 하네스는 훅에 의존하지 않습니다:feature.py는 작업 상태를 봉인하고 수동 편집 후 작동을 거부하며, 진입 파일은 모든 에이전트에게 세션 시작 시init.sh를 실행하라고 지시합니다. - Claude Code 전용,
.worktreeinclude: 프로젝트 실행을 위해.env와 같은 gitignored 파일이 필요하면 나열하여 Claude Code가 생성하는 모든 워크트리가 해당 파일의 복사본을 받도록 하세요. 일반git worktree add의 경우harness/README.md에서 해당 파일을 언급하여 사람들이 복사하도록 하세요.
9. 한 번 증명
bash scripts/harness/init.sh와 python3 scripts/harness/check_architecture.py를 실행하고 실제 결과를 보고하세요. 프로젝트(하네스가 아님) 때문에 무언가 실패하면 명확히 말하고 보고서의 첫 번째 항목으로 남겨두세요. 통과를 위해 규칙을 완화하거나 명령어를 삭제하지 마세요. 그런 다음 references/principles.md의 새 세션 테스트를 수행하세요: 파일만 사용하여 다섯 가지 질문에 답하고 답할 수 없는 것을 수정하세요.
10. 보고
간략하게 사용자에게 알리세요:
- 생성된 것, 병합된 것, 이미 존재하여 건너뛴 것
- 계층별 명령어와 각각의 출처
- 모든
TODO(confirm)및 모든 가정 - 초기화/검증 결과, 실패 포함
- 이 스킬 자체가 저장소에 설치된 경우(
.agents/skills/harness-bootstrap/또는 다른 에이전트의 스킬 폴더,skills-lock.json과 함께), 그렇게 말하세요: 팀은 부트스트랩 후에 필요하지 않으며 나중에 다시 실행하기 위해 제거하거나 유지할 수 있습니다. 직접 제거하지 마세요. - 다음 단계: 브랜치에서 부트스트랩을 검토하고 커밋한 다음
harness-start스킬(슬래시 명령어가 있는 에이전트에서는/harness-start <TASK-ID>)로 작업을 시작하세요.
사용자가 요청하지 않는 한 커밋하거나 푸시하지 마세요.
스캐폴드 적용을 위한 설계 규칙
- 프로젝트의 기존 도구를 선호하세요. 저장소에
make check가 있는Makefile이 있으면config.sh에make check를 넣고 구성 요소를 다시 나열하지 마세요. - 런타임 의존성을
bash,git,python3(표준 라이브러리만)로 유지하세요. 하네스를 위해 프로젝트에 패키지를 추가하지 마세요. - 모든 하네스 스크립트의 오류 메시지는 무엇이 실패했는지, 이유, 수정 방법을 알려야 합니다.
- 스크립트에 파괴적인 것은 없습니다. 정리는 보고만 합니다. 사람 또는 에이전트가 보고서에 따라 조치합니다.
- 가능할 때 하네스를 더 작게 만드세요. 이 저장소에서 에이전트 동작을 변경하지 않는 구성 요소는 오버헤드입니다. 완전성을 위해 설치하는 대신 그렇게 말하세요.