Files
claude-harness/AGENTS.md
T
DongHyeonka 73da7065b0 feat(template): 새 프로젝트 뼈대와 new-project.sh를 더한다
문제: 새 프로젝트마다 루트 지침, Claude Code 설정, 검증 진입점, 비전·
문제 정의 양식, 장부를 손으로 다시 만든다. 플러그인으로는 루트 문서와
권한 deny를 나눠 줄 수 없다(플러그인 CLAUDE.md·권한은 읽히지 않는다).

고른 방법: 공통 동작은 플러그인, 프로젝트 파일은 template/ 복사로
나눈다(결정 Q15). scripts/new-project.sh가 template/을 빈 폴더에 복사하고
이름·설명·마켓 주소를 바꾼 뒤 git init까지 한다. 커밋은 하지 않는다.
- AGENTS.md 양식(40줄 이하, 결정 Q2)과 CLAUDE.md(@AGENTS.md)
- .claude/settings.json: .env deny, 마켓과 harness 플러그인 켜기.
  Agent deny는 넣지 않는다(결정 Q5)
- scripts/verify.sh: 단계(docs·unit·pr·app) 뼈대와 --on <호스트> 운반부.
  작업 트리를 패치로 옮겨 기준 커밋의 새 worktree에 적용하고 트리 해시를
  맞춘 뒤 잠금 아래에서 돌린다. push하지 않는다(설계 6.1절)
- 빈 양식: docs/vision.md, docs/problem-statement.md, docs/adr/0000-template.md
- docs/ledger/: 빈 장부와 형식 설명, .gitattributes merge=union(결정 Q11)
repo 자신의 AGENTS.md·README·docs/README.md(설계와 다르게 정한 것)와
scripts/check.sh도 같이 둔다.
버린 대안: 템플릿만(공통 훅 수정이 모든 repo 손작업), 플러그인만(루트
문서·deny를 못 준다).

위험: verify.sh의 원격 운반부는 가짜 ssh(같은 기계)로만 시험했다. 실제
desktop에서는 아직 돌리지 않았다. unit·pr·app 단계 본문은 비어 있다
(종료 코드 3).

검증: scripts/check.sh 통과(플러그인 17, 템플릿 10, validate --strict).
템플릿 시험은 이름 바꾸기, 남은 {{…}} 없음, AGENTS.md 40줄 이하,
settings의 플러그인·deny, 빈 폴더가 아니면 멈춤, verify docs, 가짜 ssh로
패치 적용·트리 해시·worktree 정리와 원격 실패(종료 코드 4)를 본다.
scratchpad에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.
2026-11-08 00:02:33 +09:00

2.5 KiB

AGENTS.md — claude-harness의 정본

새 프로젝트에 바로 쓰는 Claude Code 작업 환경이다. 공통 동작(훅·스킬·스크립트)은 플러그인 harness로, 프로젝트 파일(루트 지침·설정·검증 뼈대·빈 양식)은 template/ 복사로 나눠 준다. 공개 repo다. 비밀 값·개인 경로·사내 주소를 넣지 않는다.

꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다

  1. scripts/check.sh 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
  2. 플러그인 동작을 바꾸고 plugins/harness/.claude-plugin/plugin.json의 version을 올리지 않는다(받는 쪽은 버전이 바뀌어야 갱신된다).
  3. plugins/harness/scripts/guard_bash.py의 셸 파서·H12 절을 바꾸고 소유자 기계 전역 훅(~/.claude/hooks/guard_bash.py)의 같은 절을 같이 바꾸지 않는다. 소유자 기계의 전역 훅 시험이 두 사본을 비교한다.
  4. 훅이 출력을 늘린다. 장부 훅은 아무것도 출력하지 않고, 넛지는 5줄 이하다(출력은 모든 세션의 컨텍스트에 들어간다).
  5. 훅이 표준 라이브러리 밖의 것을 쓰거나, 실패할 때 작업을 막는다(막는 것은 H12의 종료 코드 2뿐이다).

지도

  • .claude-plugin/marketplace.json: 이 repo가 곧 플러그인 마켓이다. 플러그인은 plugins/harness/ 하나다.
  • plugins/harness/: hooks/hooks.json(연결), scripts/(훅 본체·장부·techdebt), skills/(estimate·retro·techdebt), tests/.
  • template/: 새 프로젝트에 복사하는 뼈대. scripts/new-project.sh가 복사하고 이름을 바꾼다.
  • docs/: 이 repo에서 정한 것(docs/README.md)과 이 repo의 예측·실측 장부(docs/ledger/). 설계 정본은 design-docs harness/01-harness-design.md다.

검증

  • scripts/check.sh: 플러그인 시험, 템플릿 시험, claude plugin validate --strict(claude가 있을 때).
  • 훅을 고쳤으면 고장 낸 사본에서도 시험이 실패하는지 본다(조건 하나를 끌 때마다 시험 하나 이상이 실패해야 한다).

일하는 방식

  • 착수할 때 예측을, 끝날 때 실측을 docs/ledger/estimates.jsonl에 남긴다(estimate 스킬).
  • 커밋 메시지는 type(scope): 한국어 현재형 설명이고 본문은 문제 → 고른 방법과 버린 대안 → 위험 → 검증이다. AI 꼬리말을 넣지 않는다.
  • 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일은 서브에이전트에 맡긴다.