From bd6cbf0b2aa8714d96e5ce9aa5c7f8b048786463 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 22:05:18 +0900 Subject: [PATCH] =?UTF-8?q?feat(template):=20=EC=83=88=20=ED=94=84?= =?UTF-8?q?=EB=A1=9C=EC=A0=9D=ED=8A=B8=EC=97=90=20=EB=B6=84=EC=95=BC=20?= =?UTF-8?q?=EC=A0=84=EB=AC=B8=EA=B0=80=20=EB=AA=85=EB=8B=A8=20=EC=96=91?= =?UTF-8?q?=EC=8B=9D=EC=9D=84=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: new-project.sh로 만든 프로젝트에는 분야 전문가를 어디에 적고, 리드가 바뀐 경로로 무엇을 고르고, 넘김과 충돌을 어떻게 남기는지 정한 자리가 없다. lead 스킬은 그 repo의 docs/work/experts.md를 읽는다. 고른 방법: template/docs/work/experts.md(큰 그림 읽는 순서, 명단, 경로 → 렌즈, 넘김 지도, 정해 둔 충돌, 비용 재는 법)를 빈 양식으로 두고, 루트 AGENTS.md 「일하는 방식」에 한 줄, CLAUDE.md에 플러그인 새 스킬과 전문가 모양 한 줄을 더한다. 루트 40줄 상한은 그대로 지킨다. 버린 대안: 빈 .claude/skills·agents 예시 파일. 예시가 그대로 남으면 모든 세션 목록에 들어가는 빈 전문가가 된다. 위험: 양식만이라 채우기 전에는 lead가 경로표 없이 고른다(스킬이 그때는 바뀐 경로와 위험 신호로만 고르게 되어 있다). 검증: python3 -m unittest discover -s tests → 11건 통과 (새 시험: 양식의 여섯 절, AGENTS.md·CLAUDE.md가 가리키는지). --- README.md | 2 +- template/AGENTS.md | 1 + template/CLAUDE.md | 4 +-- template/docs/work/experts.md | 57 +++++++++++++++++++++++++++++++++++ tests/test_template.py | 8 +++++ 5 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 template/docs/work/experts.md diff --git a/README.md b/README.md index 1294630..024de2f 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ claude plugin install harness@claude-harness scripts/new-project.sh ~/workspace/order-service --description "주문을 받는 서비스다." ``` -복사되는 것: `AGENTS.md`(루트 지침 양식, 40줄 이하), `CLAUDE.md`(`@AGENTS.md`와 Claude 전용 줄), `.claude/settings.json`(`.env` deny, 하네스 플러그인 켜기), `scripts/verify.sh`(검증 진입점 뼈대와 원격 운반부), `docs/vision.md`·`docs/problem-statement.md`·`docs/adr/0000-template.md`(빈 양식), `docs/ledger/`(빈 장부와 형식 설명), `.gitattributes`·`.gitignore`. 이름을 바꾸고 `git init`까지 하며 커밋은 하지 않는다. +복사되는 것: `AGENTS.md`(루트 지침 양식, 40줄 이하), `CLAUDE.md`(`@AGENTS.md`와 Claude 전용 줄), `.claude/settings.json`(`.env` deny, 하네스 플러그인 켜기), `scripts/verify.sh`(검증 진입점 뼈대와 원격 운반부), `docs/vision.md`·`docs/problem-statement.md`·`docs/adr/0000-template.md`(빈 양식), `docs/work/experts.md`(전문가 명단·경로표·넘김 지도 빈 양식), `docs/ledger/`(빈 장부와 형식 설명), `.gitattributes`·`.gitignore`. 이름을 바꾸고 `git init`까지 하며 커밋은 하지 않는다. ### 있는 프로젝트에 붙이기 diff --git a/template/AGENTS.md b/template/AGENTS.md index fcec42b..9f5ea36 100644 --- a/template/AGENTS.md +++ b/template/AGENTS.md @@ -33,4 +33,5 @@ - 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬). - 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. +- 여러 분야에 걸친 일은 리드(메인 세션)가 분야 지식을 골라 새 눈 리뷰어에게 맡기고 합친다. 명단·경로표·넘김·충돌 규칙은 `docs/work/experts.md`다(Claude Code는 `lead` 스킬). - 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로) diff --git a/template/CLAUDE.md b/template/CLAUDE.md index cbbd698..3d52070 100644 --- a/template/CLAUDE.md +++ b/template/CLAUDE.md @@ -3,5 +3,5 @@ ## Claude Code에서만 - 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다). -- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다. -- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다. +- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`·`lead`(전문가 고르기·합치기)·`new-expert`(전문가 더하기)·`harness-eval`(하네스 판 비교, 시킬 때만). 플러그인 설명은 claude-harness repo의 README다. +- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다. 분야 전문가는 `paths`를 건 지식 스킬이고, 서브에이전트는 분야가 아니라 일(새 눈 리뷰·실행 검증)마다 둔다(`docs/work/experts.md`). diff --git a/template/docs/work/experts.md b/template/docs/work/experts.md new file mode 100644 index 0000000..9b17647 --- /dev/null +++ b/template/docs/work/experts.md @@ -0,0 +1,57 @@ +# 전문가 — 누가 무엇을 보고 어떻게 주고받나 + +이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 재확인 세 번까지)는 하네스 플러그인의 `lead` 스킬이고, 왜 이 모양인지는 claude-harness `docs/experts.md`다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 `new-expert` 스킬. + +```text +고치는 메인 세션 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 함정·점검표·검증대로 직접 고친다 +리드(메인 세션) ──brief + 렌즈(지식 스킬 경로)──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기 +``` + +분야 전문가는 **지식 스킬**이다. 서브에이전트는 분야가 아니라 일(새 눈 리뷰, 실행 검증)마다 둔다. + +## 1. 큰 그림을 읽는 순서 + +메인 세션과 리뷰어가 같은 순서로 읽는다. + +1. 루트 `AGENTS.md`(무엇인가 · 꼭 지킬 것 · 지도) +2. 이 문서의 자기 칸 +3. 렌즈인 지식 스킬(「함정」부터) +4. 작업 파일과 가장 가까운 폴더의 `AGENTS.md` +5. 스킬이 가리키는 정본 문서(필요한 절만) + +## 2. 명단 + +| 전문가 | 형태 | 파일 | 언제 | 내는 것 | +|---|---|---|---|---| +| 리드 | 메인 세션 + `lead` 스킬 | 플러그인 | 둘 이상 분야, PR 전, 의견 충돌 | 고른 렌즈, 합친 발견, 충돌 판정 | +| (채울 것: 분야) | 지식 스킬 | `.claude/skills/<접두>-<분야>/` | (발동 조건, `paths`) | 함정·점검표·검증 | +| (채울 것: 일) | 서브에이전트 | `.claude/agents/<이름>.md` | (새 눈 리뷰·실행 검증) | lead 공통 양식 | + +## 3. 경로 → 전문가(렌즈) + +리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. + +| 경로(glob) | 렌즈(지식 스킬) | 이럴 때 더한다 | +|---|---|---| +| (채울 것) | | | + +## 4. 넘김 지도 + +리뷰어가 「넘길 것」에 자주 쓰는 길이다. 넘김은 리드를 거친다(서로 직접 부르지 않는다). + +| 보낸 렌즈 | 받는 렌즈 | 무엇을 | +|---|---|---| +| (채울 것) | | | + +## 5. 충돌 — 이 repo에서 정해 둔 것 + +순위는 `lead` 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인 일관성 → 단순함). 같은 충돌이 두 번 나오면 여기에 한 줄 더한다. + +| 날짜 | 부딪친 것 | 정한 것 | 근거 | +|---|---|---|---| + +## 6. 비용 + +- 서브에이전트 설명은 모든 세션의 컨텍스트에 들어간다. 이 repo 서브에이전트 설명의 합을 재고(예: `grep -h '^description:' .claude/agents/*.md | wc -c`) 늘면 줄인다. +- 지식 스킬은 `paths`를 걸어 그 파일을 만질 때만 목록에 뜨게 한다. +- 전문가를 더하거나 바꾼 뒤 첫 큰 일은 `harness-eval`로 바꾸기 전과 견준다. diff --git a/tests/test_template.py b/tests/test_template.py index 5672023..46ee1a2 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -67,6 +67,14 @@ class NewProjectTest(unittest.TestCase): self.assertFalse([d for d in deny if d.startswith("Agent")], "Agent 금지는 넣지 않는다(결정 Q5)") self.assertFalse([d for d in deny if "example" in d]) + def test_experts_manual_skeleton_is_copied_and_routed(self): + manual = read(self.path("docs", "work", "experts.md")) + for section in ("## 1. 큰 그림을 읽는 순서", "## 2. 명단", "## 3. 경로 → 전문가", "## 4. 넘김 지도", + "## 5. 충돌", "## 6. 비용"): + self.assertIn(section, manual) + self.assertIn("`docs/work/experts.md`", read(self.path("AGENTS.md"))) + self.assertIn("`lead`", read(self.path("CLAUDE.md"))) + def test_ledger_and_git_are_ready(self): self.assertEqual(read(self.path("docs", "ledger", "estimates.jsonl")), "") self.assertIn("estimates.jsonl merge=union", read(self.path(".gitattributes")))