57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
# 강제기 우선 MVP 설계 (.claude 슬라이스)
|
|
|
|
- 작성일: 2026-07-05
|
|
- 대상: `company-haness` / Org OS — 명세를 처음으로 **실행 시점에 강제**하는 층
|
|
- 범위: 강제기(hook/validator) 중심 + 최소 실제 구조. git 미사용.
|
|
- 뿌리 대응: 리뷰의 ①강제 공백 ②자기신고 — 명세로는 불가했던 부분을 코드로 강제.
|
|
|
|
## 1. 아키텍처
|
|
Claude Code hook은 stdin JSON + exit code로 동작한다. exit(2)는 툴콜/종료를 **하드 차단**하고 사유를 되먹인다(disler 패턴). 이 결정론 스크립트들은 이 세션에서 독립 테스트가 가능하다. 자동 라우팅·전체 오케스트레이션 루프는 런타임이 세션 로드시 구동하므로 MVP는 그 아래 **강제층을 완성·검증**한다.
|
|
|
|
## 2. 컴포넌트 (단일 책임)
|
|
| 파일 | 책임 | 입력 → 출력 |
|
|
|---|---|---|
|
|
| `.claude/hooks/gen_agents.py` | capability-families.yaml → `.claude/agents/*.md` 생성 | families → 26 agent .md |
|
|
| `.claude/hooks/validate_report.py` | 보고서가 org-os 계약 준수 검증 | report.yaml → exit 0/2 |
|
|
| `.claude/hooks/guard_tools.py` | tool-permission-matrix 강제 | PreToolUse JSON → exit 0/2 |
|
|
| `.claude/hooks/stop_validate.py` | SubagentStop시 보고서 찾아 validate 호출 | stdin JSON → exit 0/2 |
|
|
| `.claude/settings.hooks.json` | hook 배선 템플릿(활성화=다음 세션) | — |
|
|
| `.claude/commands/ceo-intake.md` | 진입 command(구조 시연) | — |
|
|
| `.claude/tests/test_enforcement.py` | good/bad 픽스처 + exit-code 단언 | → all green |
|
|
|
|
## 3. 강제 계약
|
|
### validate_report.py (자기신고 접지 + BLUF)
|
|
보고서 yaml에 대해:
|
|
- `report-header.bottom-line` 비면 차단(answer-first).
|
|
- `evidence[]` 비었거나 `source-uri`가 실존 파일이 아니면 차단(자기채점 차단). command+exit-code 형태도 허용.
|
|
- `confidence.value == High`인데 grade ≥ E3 증거 또는 성공 실행 아티팩트 0개면 차단(과잉확신 차단).
|
|
- 필수 필드(bottom-line, decision-needed, confidence, risks, evidence) 누락 차단.
|
|
- 통과 exit 0, 위반 stderr 사유 + exit 2.
|
|
|
|
### guard_tools.py (최소권한)
|
|
`tool-permission-matrix.yaml` default-deny(slack/github-pr-create/deploy/secret-read/db-write) 위반을 차단:
|
|
- Bash 명령의 위험 패턴(git push, gh pr create, deploy/kubectl, `.env`/secret 접근, rm -rf) → exit 2.
|
|
- 그 외 → exit 0. 사유는 stderr로 Claude에 되먹임.
|
|
|
|
## 4. gen_agents 생성 규칙
|
|
각 family → `.claude/agents/<family-id 소문자>.md`:
|
|
- frontmatter: `name`(소문자-하이픈), `description`(= capability + "Use PROACTIVELY when <triggers>. Do NOT use for <exclusions>."), `tools`(family유형별 최소권한), `model: inherit`.
|
|
- body: "When invoked" 넘버드 스텝 + **report-header(BLUF) 필수** + exclusions 준수 + tier=heavy는 plan-signoff 전 실행 금지.
|
|
- tools 매핑: 엔지니어링/실행 family=Read,Grep,Glob,Edit,Write,Bash; 감사(audit-capable)=Read,Grep,Glob,Bash; 임원/추천=Read,Grep,Glob,Write; orchestrator=Read,Grep,Glob,Write,Edit.
|
|
|
|
## 5. 테스트 (이 세션 검증)
|
|
- validate_report: 정상→0, BLUF누락/증거허위/과잉확신→각 2.
|
|
- guard_tools: 허용도구→0, deny(gh pr create/`.env`/rm -rf)→각 2.
|
|
- stop_validate: 픽스처 보고서(정상/불량)→0/2.
|
|
- gen_agents 실행 → 26 agent 생성 + frontmatter 파싱·description에 triggers/exclusions 포함 검증.
|
|
- `test_enforcement.py` 한 방 all green.
|
|
|
|
## 6. 범위 밖(다음)
|
|
전체 오케스트레이션 라이브, 7 command 전부, MCP, evidence 등급 CI 파생, settings.json 라이브 활성화(자기간섭 방지 위해 템플릿으로 제공).
|
|
|
|
## 7. 성공 기준
|
|
1. 4개 스크립트 모두 정상/위반 픽스처에서 기대 exit code.
|
|
2. gen_agents가 26개 agent .md 생성, 전부 유효 frontmatter.
|
|
3. test_enforcement.py exit 0(all pass).
|
|
4. 기존 org-os 정합성 게이트 무회귀.
|