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

21 lines
3.2 KiB
Markdown

# 이 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 마켓을 받는지는 보지 않았다(소유자는 데스크톱 앱 로컬 세션만 쓴다).