강제기 우선 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 . Do NOT use for ."), 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. 성공 기준

4개 스크립트 모두 정상/위반 픽스처에서 기대 exit code.
gen_agents가 26개 agent .md 생성, 전부 유효 frontmatter.
test_enforcement.py exit 0(all pass).
기존 org-os 정합성 게이트 무회귀.

3.9 KiB Raw Blame History