Files
claude-harness/docs/README.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

3.2 KiB

이 repo에서 정한 것

설계 정본은 design-docs harness/01-harness-design.md다(11절 하네스 템플릿 repo, 13절 소유자 결정 2026-11-07). 이 문서는 만들면서 설계와 다르게 정했거나 설계에 없던 것만 적는다.

# 정한 것 설계와 다른 점 근거
1 H12는 force push, 범위 밖 rm -r, DB·볼륨·migration 삭제만 막는다 설계 5.1절의 git reset --hard·git clean -fdx·git checkout -- . 줄은 넣지 않았다 소유자 기계 세션 기록의 Bash 명령 43,078개에서 정당하게 쓴 경우가 각 61·32·31건이었다. 막으면 거짓 양성이 크다. 자기 작업 폴더 안에서만 효과가 있고, auto mode 분류기가 따로 본다
2 다른 기계 작업 사본 경로(host:/abs/path)로 보내는 force push는 통과(보호 브랜치를 덮거나 ref가 없으면 막음) 설계는 force push를 모두 막는다 같은 기록의 force push 25건이 모두 desktop 작업 사본으로 시험 브랜치를 옮기는 운반이었다. 공유 원격(Gitea)으로 보낸 것은 0건
3 -p <이름>을 준 compose down -v는 통과 설계는 down -v를 모두 막는다 시험 lane은 고유 -p로 띄우고 같은 -p로 볼륨까지 지우는 것이 정해진 절차다(백엔드 scripts/run-compose-runtime-smoke.sh). 막을 것은 -p 없는 기본 프로젝트(개발 데이터)다
4 kubectl delete는 pvc·pv·namespace만 설계는 kubectl delete 전부 pod 지우기는 컨트롤러가 다시 만든다(되돌릴 수 있다). 기록에 정당한 pod 재시작이 있었다
5 rm -r은 /tmp 아래를 허용, /tmp/claude-<uid> 자체는 막음 설계는 scratchpad와 /tmp/claude-<uid>만 빌드 도구가 /tmp에 만든 임시 폴더를 지우는 정당한 경우가 있었다. /tmp는 원래 버려도 되는 곳이다
6 원격(ssh '…') rm -r은 너무 넓은 대상만 막는다(~, ~/workspace/<이름> 통째, /와 그 바로 아래) 설계에 없음 원격 작업 폴더를 알 수 없다. desktop 작업 폴더 통째 지우기 2건은 막힘으로 남긴다(git worktree remove가 맞는 길)
7 플러그인 H12는 사용자 전역 설정에 guard_bash.py … H12가 있으면 건너뛴다 설계 Q13 (c)의 「두 번 돌지 않게」를 구체화 소유자 기계는 전역 훅이, 다른 기계·파생 서비스는 플러그인이 막는다. 판정 코드는 두 곳이 같고 소유자 기계의 전역 훅 시험이 비교한다
8 장부 훅은 ~/.claude/harness/에 쓰고, repo 장부(docs/ledger/estimates.jsonl)에는 스킬만 쓴다 설계 10.2절과 같음. 13절 Q11대로 repo마다 장부 훅이 repo 파일을 고치면 모든 세션의 작업 트리가 더러워진다
9 template/.claude/settings.json에 Agent deny를 넣지 않는다 설계 11.2절 그림에는 있다 13절 Q5(Agent 금지 해제)

확인한 것과 못 한 것

  • 이 repo 첫 작업의 시험·설치 결과는 docs/ledger/estimates.jsonl 첫 줄과 design-docs 공유 노트 h2-harness-repo.md에 있다.
  • 클라우드 세션에서 Gitea 마켓을 받는지는 보지 않았다(소유자는 데스크톱 앱 로컬 세션만 쓴다).