1주차 - 동작하는 OS 뼈대

[ssamzag]

1. 소개

SDD(스펙 주도) + TDD(테스트 주도) 기반의 3단계 사람–AI 협업 파이프라인.
전체 사이클을 돌려보는 게 목적이며 고도화시 단계는 늘어날 예정입니다. 각 사이클은 요구 한 줄 → 커밋으로 끝나며, 사람이 개입하는 지점은 3회입니다.

요구 한 줄 → [SPEC] → [PLAN] → [BUILD] → 커밋
             승인①    확인②     승인③

---

2. 헌법 (위반 판정 가능한 규칙)

AI가 절대 어길 수 없는 규칙. 위반이 필요하면 멈추고 사람에게 보고합니다.

ID	규칙
H1	검증 근거는 **테스트 러너 출력 전문(全文)**뿐. "통과했습니다" 류 자기보고는 검증 아님
H2	테스트 작성과 구현은 컨텍스트 분리. test-writer ≠ implementer
H3	build 단계 동안 src/test/**는 read-only (훅으로 강제). 테스트가 틀렸으면 수정 말고 이의 제기
H4	게이트는 산출물 검사. 산출물 없거나 미달이면 다음 단계 진행 불가
H5	테스트 통과 = 완료 아님. build 출구는 verifier 감사를 통과해야 열림
H6	위반은 즉시 적립. /m-retrospect를 기다리지 않고 그 자리에서 CLAUDE.md에 기록

핵심 설계 사상: 쓰는 에이전트 ≠ 검증하는 에이전트. 코드를 쓴 주체가 스스로 채점하는 편향(치팅)을 구조적으로 차단하고, 그 규칙을 사람의 선의가 아니라 훅으로 강제한다.

---

3. 3단계 파이프라인

단계	스킬	입력 → 산출물	게이트 (사람 개입)	담당 에이전트
1. SPEC	/m-spec	요구 한 줄 → specs/NNN-spec.md (Q&A + Given/When/Then + 충돌 분석)	① 스펙 승인	spec-writer, conflict-analyzer
2. PLAN	/m-plan	승인 스펙 → specs/NNN-plan.md (인터페이스 + 대응표) + 실패하는 테스트	② 대응표 확인 (시나리오 1:1↑ 커버)	메인 + test-writer
3. BUILD	/m-build	태스크 + 테스트(read-only) → 프로덕션 코드 + 감사 보고	③ 최종 승인 → 커밋	implementer → tdd-refactor → verifier

BUILD 내부 루프: ① GREEN(구현→러너 즉시 실행, 3회 연속 실패 시 에스컬레이션) → ② REFACTOR(선택, 동작 불변) → ③ verifier 감사(실행 테스트 수 = 대응표 수, src/test/** diff 없음, 러너 전문 첨부).

---

4. 스킬 (Skills) — .claude/skills/

스킬	위치	역할
m-brainstorm	진입 전	소크라테스식 문답으로 막연한 아이디어를 '요구 한 줄'로 수렴 (read-only)
m-spec	1단계	요구 → 인터뷰 → Given/When/Then, 충돌 분석 후 승인
m-plan	2단계	승인 스펙 → 인터페이스 스케치 + 태스크 + 실패하는 테스트
m-build	3단계	구현 → 감사 → 최종 승인 후 커밋
m-tdd	파이프라인 밖	경량 진입점. 스펙·phase·게이트 없이 요구 한 줄에서 바로 RED→GREEN→REFACTOR. 언어·런너 자동 감지 후 tdd에 위임
m-retrospect	유틸리티	AI가 틀린 것을 CLAUDE.md 회고 로그에 한 줄씩 적립 (H6)
m-status	유틸리티	현재 phase·진행도·미커밋 변경·다음 스텝 리포트 (read-only)

---

5. 에이전트 (Agents) — .claude/agents/

정식 파이프라인 (§3):

에이전트	단계	역할	헌법
spec-writer	m-spec	인터뷰 → Given/When/Then 시나리오	—
conflict-analyzer	m-spec	기존 specs/ 전체 대비 충돌·중복·영향 분석 (spec-writer와 분리 컨텍스트)	—
test-writer	m-plan	시나리오 → 컴파일되는 실패하는 테스트 (implementer와 분리)	H2
implementer	m-build	테스트 통과 최소 구현. 테스트 수정 불가	H2, H3
tdd-refactor	m-build	GREEN 유지 리팩터. 동작 불변, 단계별 러너 확인	H3
verifier	m-build	러너 출력 전문 대조 감사. 통과해야 커밋 게이트 열림	H1, H5

/m-tdd 경량 진입점 전용 (파이프라인 밖):

에이전트	역할
tdd	RED→GREEN→REFACTOR 오케스트레이터. 아래 3개를 순서대로 스폰
tdd-test-writer	RED 테스트 작성. 프로덕션 코드 열람 금지 (H2)
tdd-implementer	GREEN 최소 구현. 테스트 read-only (H3)
(REFACTOR)	위 tdd-refactor 공유

---

6. 훅 (Hooks) — .claude/hooks/

헌법을 코드로 강제하는 장치. settings.local.json에 트리거가 등록되어 있다.

훅	트리거	역할	헌법
session-guard.sh	SessionStart	OS.md 존재 확인 + 현재 phase를 세션 컨텍스트로 주입	지원
test-guard.sh	PreToolUse(Write|Edit)	phase==build일 때 src/test/** 쓰기 차단	H3
commit-guard.sh	PreToolUse(Bash)	① build phase에서 git commit 차단 ② conventional 형식 아니면 차단	H5
skill-stat.sh	PostToolUse(Skill)	스킬 호출을 .claude/skill-stats.log에 기록 (과제용 통계)	§6

.claude/phase 파일이 상태 스위치다. /m-build 진입 시 build로 설정되고, 커밋 또는 에스컬레이션 시 해제된다. 비어 있으면 test-guard·commit-guard는 차단하지 않는다.

---

한눈에 보는 흐름

brainstorm → m-spec → m-plan → m-build → (commit)
   아이디어    시나리오   테스트생성   구현+감사
             [spec-writer] [test-writer] [implementer→tdd-refactor→verifier]
             [conflict-      ← 훅이 각 단계 규칙을 강제 (test/commit-guard) →
              analyzer]

리뷰 요청이 좀 늦었습니다. 잘 부탁드립니다.

지금은 OS를 안 쓰고 각각 요청하는 게 더 결과물이 더 좋네요. :(
계속해서 연구해 보겠습니다!