Skip to content

refactor(harness): migrate references/ into .agents/ and slim CLAUDE.md#33

Merged
pko89403 merged 8 commits into
mainfrom
refactor/harness-layout-split
Apr 23, 2026
Merged

refactor(harness): migrate references/ into .agents/ and slim CLAUDE.md#33
pko89403 merged 8 commits into
mainfrom
refactor/harness-layout-split

Conversation

@pko89403

@pko89403 pko89403 commented Apr 23, 2026

Copy link
Copy Markdown
Owner

한 줄 요약

  • references/에 섞여 있던 local-adaptation(정책)과 체크리스트 4종을 .agents/policies/·.agents/playbooks/로 분리하고, CLAUDE.md를 도메인 상세가 없는 스키마/거버넌스 레이어로 슬림화합니다.

배경 / 문제

  • 기존 상태: references/가 local-adaptation + 체크리스트 + upstream archival을 혼합 보관했고, CLAUDE.md는 기술 스택·모듈 표·CLI·Codex commands 같은 도메인 구체를 직접 들고 있어 스스로 선언한 "스키마 레이어" 역할과 어긋났다.
  • 문제: 하네스 파일이 .agents/와 references/ 두 루트에 분산돼 있었고, drift 비교 이력 없이 references/upstream-*.md 스냅샷만 archival로 남아 있었다.
  • 이번 PR의 목표: .agents/ 단일 루트로 하네스 레이아웃을 통합하고, CLAUDE.md는 스키마 + 7개 운영 원칙까지로 축소.

PR 대시보드

항목 내용
유형 refactor / chore
영향 범위 harness / docs / tests
동작 변경 없음 (paths-only)
Breaking Change 없음
관련 이슈 -
기준 브랜치 main

변경 묶음별 리뷰 가이드

변경 묶음 파일/디렉토리 무엇이 바뀌었나 리뷰 포인트 실행 없이 보는 법
Layout 이동 references/ 전체, .agents/policies/, .agents/playbooks/ references/local-adaptation.md → .agents/policies/, 체크리스트 4종 → .agents/playbooks/ (접미사 -checklist·-patterns 제거), references/upstream-*.md + references/README.md 삭제 rename이 100% 유지됐는지, upstream 스냅샷 삭제가 수용 가능한지 git log --stat, git show <commit> --name-status
Schema/Domain 분리 CLAUDE.md, .agents/policies/local-adaptation.md CLAUDE.md에서 도메인 표/CLI/Codex command 리스트 제거 → 포인터만. local-adaptation.md에 Primary Tech Stack, Main Modules, Repo-local Codex Commands, Language Conventions 신설 "스키마 vs 도메인" 책임 경계가 선언과 일치하는지 CLAUDE.md(≤85줄)와 local-adaptation.md 대조
경로 치환 13개 SKILL.md, README.md / README.ko.md, .github/, .graphifyignore, scripts/execute.py, tests/ 모든 references/... 참조를 새 경로로 치환 stale references/ 언급이 남지 않았는지 grep -rn "references/" .
테스트 tests/test_graphify_harness.py, tests/test_execute_script.py PR 규칙 테스트 경로 + _load_guardrails fixture 경로 갱신 test_pr_creation_rules_require_template_based_flow, test_load_guardrails_uses_repo_specific_documents 의미 유지 테스트 이름 + assertion 대조
Cleanup references/skill-anatomy.md 중복 문서 제거 삭제가 안전한지 (참조 없음) grep -rn "skill-anatomy"

Before / After

Before

  • references/local-adaptation.md + references/{security,performance,accessibility}-checklist.md + references/testing-patterns.md + references/upstream-{AGENTS,README}.md
  • CLAUDE.md가 기술 스택·모듈 표·CLI·Codex commands 포함
  • .graphifyignore에 존재하지 않을 예정인 references/ 줄

After

  • .agents/policies/local-adaptation.md (정책 + 도메인 상세 집결지)
  • .agents/playbooks/{security,performance,accessibility,testing}.md (rename 후 일관된 네이밍)
  • CLAUDE.md 83줄로 슬림화 (스키마 + 7개 운영 원칙 + 3-레이어 아키텍처)
  • upstream archival 제거 (drift 비교 수동 이력이 없어 효용 부재)

검증

항목 결과 근거
테스트 ✅ uv run pytest --ignore=tests/test_mlx_runtime.py --ignore=tests/test_cli_smoke_mlx.py --ignore=tests/test_graphify_auto_refresh.py -q → 141 passed (pre-push 게이트 그대로)
린트 ✅ uv run ruff check . → All checks passed
타입체크 ✅ uv run mypy src → no issues
경로 정리 ✅ grep -rn "references/" 실제 소스 0 hit (Path Mapping 표의 upstream 지시 1건만 의도적으로 유지)

남은 리스크 / 후속 작업

  • .agents/vendor/upstream/ 같은 추가 분화가 필요해지면 별도 PR로 검토
  • 주의할 점: pre-rebase 로컬에 있던 graphify refresh 커밋 2개(chore(graphify): refresh graph after harness split, ...after layout split)는 rebase 시 graphify-out/* 충돌로 skip했습니다. 현재 graphify-out/은 main(fdb0c71)의 code refresh 결과이며, scripts/hooks/graphify-auto-refresh.sh가 inputs unchanged로 판정해 별도 refresh 커밋 없이 유지.
  • 리뷰 시 특히 볼 부분: 경로 일괄 치환이 "체크리스트 맥락 → .agents/playbooks/" vs "정책/로컬 적응 맥락 → .agents/policies/"로 구분돼 들어갔는지

Codex and others added 8 commits April 23, 2026 13:12
@claude
chore(references): remove redundant skill-anatomy.md
ba1f47f 
The anthropic-skills:skill-creator skill already encodes the frontmatter,
standard sections, and anti-rationalization conventions this file documented.
Remove references/skill-anatomy.md and its index entry to drop the duplicate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
refactor(harness): split schema and domain across CLAUDE.md, local-ad…
4496052 
…aptation, and graphify-manager

Realign three active documentation surfaces with their declared roles:

- CLAUDE.md (= AGENTS.md symlink): schema, 3-layer architecture, 7 operating
  principles, PR rules. 152 -> 83 lines.
- references/local-adaptation.md: tech stack, main modules, validation commands,
  Repo-local Codex commands, path mapping, language conventions. 78 -> 123 lines.
- .agents/skills/graphify-manager/SKILL.md: full refresh orchestration, committed
  artifacts, and `graphify update .` ban (previously embedded across CLAUDE.md
  and local-adaptation.md).

Side changes:
- Update docs-manager sync targets to include graphify-manager SKILL.md.
- Rewrite .github/copilot-instructions.md read order across three surfaces.
- Simplify test_claude_delegates_graphify_details_to_graphify_manager_skill to
  check the boundary pointer only; move internal SKILL.md assertions into the
  existing test_graphify_manager_skill_exists_with_full_refresh_flow.

Tests: 124 passed; 2 network-dependent graphify_producer tests skipped in the
sandbox.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
refactor(layout): split references/ into .agents/policies/ and .agent…
90ab38a 
…s/playbooks/

Move harness-local docs out of references/ into the .agents/ namespace so
the agent-harness files sit under a single root.

- git mv references/local-adaptation.md -> .agents/policies/local-adaptation.md
- git mv references/{security,performance,accessibility}-checklist.md
  and references/testing-patterns.md -> .agents/playbooks/{security,performance,accessibility,testing}.md
- Drop references/{README,upstream-AGENTS,upstream-README}.md (upstream
  drift snapshot no longer maintained)
- Update in-repo path references in skill SKILL.md files,
  docs-manager/doc-manager agents yaml, CLAUDE.md, README.md, README.ko.md,
  raw/README.md, .github/pull_request_template.md,
  .github/copilot-instructions.md, tests/test_graphify_harness.py,
  tests/test_execute_script.py, and scripts/execute.py GUARDRAIL_FILES
- Remove obsolete references/ entry from .graphifyignore

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
chore(harness): address PR review — drop stale Path Mapping row, norm…
1a5e962 
…alize playbook H1s

- `.agents/policies/local-adaptation.md`: drop the `references/` Path Mapping row
  (upstream agent-skills doesn't mandate `references/` as a hard convention,
  and no in-repo consumer references the old path anymore)
- `.agents/playbooks/{security,performance,accessibility,testing}.md`: drop
  `-Checklist` / `-Reference` suffix from the H1 to match the filename rename

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
chore(graphify): refresh graph after harness layout split
c17cafc 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
refactor(hooks): slim Stop hook to ruff-only (mypy/pytest stay on pre…
aed217f 
…-push)

Stop hook은 fire-and-forget (exit 2 차단 불가) + 에이전트 응답 종료마다
실행되는 hot-path다. 매 턴 ~3s mypy+pytest는 핫패스 원칙 위반이고
차단 효과도 없어 `pre-push.sh`의 동일 검증과 중복.

- `scripts/hooks/claude-stop-checks.sh`에서 `uv run mypy src` / `uv run pytest`
  블록 제거, `ruff check .`와 `ruff format --check .`만 유지
- `tests/test_execute_script.py::test_claude_stop_script_uses_repo_validation_chain`
  의 assertion을 현실에 맞게 갱신 (mypy/pytest가 **없어야** 함을 검증)

pre-push.sh는 그대로 유지 — mypy/pytest 전체 게이트는 push 직전 1회로 위임.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
refactor(hooks): extract inline settings.json hooks into scripts, use…
d0345d8 
… exit 2 for blocks

JSON에 박힌 인라인 bash (regex + grep + sed, 이중 이스케이프)는
shellcheck 불가, syntax highlighting 불가, unit test 불가, diff 리뷰 난해.
차단 hook이 `exit 1`을 쓰고 있어 Claude Code 스펙상 실제로는
non-blocking error로 처리되던 버그까지 동시 교정.

신규 스크립트 5개 (`scripts/hooks/`):
- `pretool-block-destructive.sh` — PreToolUse:Bash, **exit 2** (차단 정상화)
- `pretool-warn-package-remove.sh` — PreToolUse:Bash, exit 0 (경고)
- `pretool-block-graphify-out.sh` — PreToolUse:Write/Edit, **exit 2** (차단 정상화)
- `pretool-warn-secret-file.sh` — PreToolUse:Write/Edit, exit 0 (경고)
- `posttool-check-secrets-on-git.sh` — PostToolUse:Bash, git add/commit 감지 시
  `check-secrets.sh` 실행

`.claude/settings.json`은 matcher + `bash scripts/hooks/<name>.sh` 호출만
남도록 슬림화 (Write/Edit 공통 로직 2개는 동일 스크립트 재사용).

`tests/test_graphify_harness.py::test_claude_settings_enable_repo_specific_safety_hooks`
의 command 문자열 검증을 `"graphify-out/"` → `"graphify-out"`으로 완화
(스크립트 경로엔 슬래시가 없음 — 이름에는 dash로 포함).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@claude
fix(hooks): block on secret detection (exit 2) instead of warn-only
70491b8 
Security-invariant hook은 warn-only로 두는 게 Claude Code hook 철학의
anti-pattern 3번과 정면 충돌. 감지 시 exit 2로 전환해 Claude에게 "반드시
rollback/재작업" 신호를 주입. 개별 탐지 라인의 `WARN:` 프리픽스는 진단
정보로 남기고, 최종에서 `BLOCKED:` + exit 2로 차단.

PostToolUse는 이미 실행된 git add/commit을 되돌리진 못하지만, exit 2가
에이전트에게 전달돼 다음 턴에 rollback을 강제. 사람 로컬 commit 차단은
.githooks/pre-commit 통합이 별도 후속 (노션 §8에 기록).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pko89403 pko89403 merged commit 8a2c00e into main Apr 23, 2026
2 checks passed
@pko89403 pko89403 deleted the refactor/harness-layout-split branch April 23, 2026 06:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@pko89403