claudie-workflow Step 003 설계 v2 — 인코딩 수정

044_spec-frontmatter.md

Decision 044: 스펙 Frontmatter 및 History 설계

결정

스펙 frontmatter에서 parent만 수동 관리하고 children은 스크립트가 자동 계산한다. staleness는 review_at 필드 대신 문서 내 History 섹션으로 관리한다.

Frontmatter 스키마

---
id: L2-007
title: "로컬 drift 감지"
type: spec
level: L2
status: planned            # planned | done | discarded
parent: L1-002
related_decisions: [042, 044]
created: 2026-04-16
---

parent만 수동, children 자동인 이유

양방향 수동 관리 시 불일치 리스크가 높음 — L2-007의 parent를 L1-002에서 L1-003으로 바꿨는데 L1-002의 children에서 L2-007을 빼는 걸 잊으면 RTM이 깨짐. parent만 수동이면 진실이 하나(parent 필드)이고, children은 그로부터 파생되므로 불일치가 구조적으로 불가능.

review_at 대신 History인 이유

review_at은 "다음 리뷰 예정일"이라는 단일 데이터포인트에 불과. 문서의 전체 이력(언제 만들었는지, 언제 리뷰했는지, 무슨 변경이 있었는지)을 History 로그로 관리하면 staleness 판단에 더 풍부한 정보를 제공. 마지막 reviewed 엔트리의 날짜만 봐도 staleness를 판단할 수 있음.

History 섹션

문서 하단에 위치. 로그 타입:

• created — 문서 최초 생성 (scaffold 자동)
• reviewed — 리뷰/constitution check 통과
• done — planned → done 전환
• discarded — planned → discarded 전환
• archived — archive 처리
• note — 기타 (스펙 의미 변경, 참고사항 등)

updated 타입을 뺀 이유

"updated"는 "뭘 업데이트했는지"를 안 담으므로, 어차피 설명을 써야 하면 note로 충분. "오타 수정도 updated인가, 전면 재작성도 updated인가" 같은 기록 기준 모호성도 제거됨.

예시

## History
- 2026-04-16 created: 초기 작성
- 2026-04-17 note: Input 섹션에 timeout 파라미터 추가 (L3-012 반영)
- 2026-04-20 reviewed: constitution check 통과
- 2026-04-22 done: PR #42 merge

045_spec-lifecycle.md

Decision 045: 스펙 Lifecycle 단순화

결정

스펙 lifecycle을 planned/done/discarded 3상태로 단순화한다. Decision 027(planned → started → evolve → confirmed)을 대체한다.

상태 정의

• planned: 이 스펙이 필요하다는 것은 확정. 내용은 비어있을 수도, 작성 중일 수도 있음.
• done: 리뷰 완료, 확정. 바꾸려면 새 스펙이나 amendment.
• discarded: 기능 제거 또는 방향 전환으로 폐기. RTM에서 "왜 사라졌는지" 추적용.

왜 이렇게 결정했는가

evolve 제거 이유

started와 evolve의 경계가 모호했음. "작업 시작했다"와 "작업 중이다"가 실질적으로 같은 상태인데 별도 상태값으로 관리하는 것은 overhead만 증가.

draft 대신 planned인 이유

처음에는 draft/confirmed(2상태)를 고려했으나, planned가 "필요성은 확정됐지만 내용은 아직"이라는 의미를 더 정확히 표현. draft는 "작성 중"이라는 뉘앙스만 있어서 "아직 안 시작한 스펙"과 "한창 쓰고 있는 스펙"을 구분 못 함.

confirmed 대신 done인 이유

더 직관적이고 짧음.

discarded 추가 이유

최초 draft/confirmed에서는 누락됐던 케이스. 기능 제거·방향 전환 시 RTM에서 해당 스펙과 하위 스펙이 왜 사라졌는지 추적할 수 없으면 cascade 문제 감지가 안 됨.

"작성 중" 상태는?

별도 상태 없음. planned 문서에 내용이 채워지고 있으면 그게 "작성 중". History 섹션의 note 엔트리들이 시간 흐름의 흔적을 남김.

History 섹션이 대체하는 것

기존 4상태(planned/started/evolve/confirmed)가 캡처하려 했던 "언제 만들었고, 언제 작업 시작했고, 뭐가 바뀌었는지"를 History 로그가 전부 기록한다.

051_sdd-l0l4-pipeline.md

Decision 051: SDD Pipeline → L0-L4 매핑

결정

SDD의 specify/plan/tasks 파이프라인을 L0-L4에 대응시킨다. 궁극적으로 c-epic start L4-010 한 번에 완료까지 가는 것이 비전이다.

매핑

SDD pipeline        L0-L4
───────────────     ──────────────────────
Constitution    →   L0 Vision + Constitution 원칙
specify         →   L1 Journey / L2 Feature
plan            →   L3 Technical
tasks           →   L4 Task/Test
implement       →   c-epic start L4-xxx

흐름

1. 사용자가 L1 또는 L2 수준의 입력을 준다 (정말 다양한 종류 — UI, 백엔드, 인프라, 기획, full-feature 등)
2. AI가 입력의 종류에 따라 사전 등록된 thinking process 중 적합한 것을 추천한다 (decision 049)
3. 사용자가 confirm한다 (자동화 모드면 AI가 선택)
4. 선택된 thinking process를 거쳐 L3 Technical, L4 Task/Test까지 구체화한다
5. 각 L4는 LLM이 한 번에 완료할 수 있는 의미 있는 단위 (decision 050)
6. c-epic start L4-010 → ralph-loop 등을 통해 거의 한 방에 완료까지 진행

SDD에서의 핵심 인사이트

SDD 조사(Martin Fowler, GitHub Spec Kit, Panaversity)에서 나온 핵심:

• 스펙이 충분히 상세하면 30분 스펙 작성으로 4-8시간 구현을 자동화 가능
• 병목이 "얼마나 빠르게 코딩하는가"에서 **"얼마나 잘 정의하는가"**로 이동
• spec-kit의 3단계: /speckit.specify → /speckit.plan → /speckit.tasks — 이것이 L1/L2 → L3 → L4에 대응

왜 이렇게 결정했는가

• 기존 c-epic 워크플로우에서 플랜 수립 → 구현의 흐름이 이미 존재하지만, 스펙의 granularity가 정의되어 있지 않아 LLM이 한 번에 처리할 단위가 불명확했음
• L4까지 구체화하면 각 단위가 작고 명확해져서 LLM 성공률이 올라감
• thinking process를 입력 종류별로 분기하면 "UI 기능인데 데이터 모델부터 설계하는" 같은 비효율을 방지

현재 한계

• 처음부터 모든 것을 할 수는 없음 — opinionated 버전 먼저 (decision 052)
• dogfooding으로 실제 사용하면서 개선 (decision 053)
• thinking process 의 구체적 정의는 아직 미완성 — 초기 타입 예시만 존재

constitution.md

Constitution

정의

SDD(Spec Driven Development)에서 모든 스펙과 구현에 적용되는 불변·비타협 원칙의 집합.

개별 feature 스펙이 "무엇을 할지"를 정의한다면, Constitution은 "어떻게 만들어야 하는지"를 강제한다. Architectural DNA.

핵심 특성

• 개별 feature에 종속되지 않음 — 모든 스펙, 모든 구현에 적용
• 외부 체크리스트 + hooks로 enforcement (decision 041, 가설) — Claude 자체의 self-check는 실패율 높음
• 하나라도 위반하면 다음 단계로 넘어갈 수 없음
• 세션, subagent 경계를 넘어 지속적으로 적용

claudie-workflow에서의 Constitution 후보

• decision 038: LLM 병신짓 구조적 차단 (자가 승인 금지, 검증 없는 완료 보고 금지)
• decision 036: Self-contained 필수 (외부 참조 금지)
• decision 032: Silent failure 금지 (모든 실패에 메시지)
• decision 025: LLM attention 분산 방지 + 사기 방지

참고 출처

• Agent Factory — The Project Constitution: https://agentfactory.panaversity.org/docs/General-Agents-Foundations/spec-driven-development/the-project-constitution
• Martin Fowler — SDD: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
• GitHub Spec Kit: https://github.com/github/spec-kit

data-dictionary.md

Data Dictionary — claudie-workflow

이 프로젝트에서 사용하는 용어 중 LLM이 잘못 해석할 가능성이 높은 것 위주로 정의. 새 세션에서 용어를 멋대로 해석하는 것을 방지하는 것이 목적. 각 용어는 docs/dd/{term}.md 개별 파일로 관리.

---

Index

• Constitution — SDD의 불변 원칙 집합. 모든 스펙/구현에 적용, 독립 에이전트가 검증, 위반 시 차단.
• SDD — Spec Driven Development. 스펙이 코드보다 상위 권위.
• RTM — Requirements Traceability Matrix. L0-L4 레벨 간 추적성 관리.
• L0-L4 — 스펙 granularity 계층. Vision → Journey → Feature → Technical → Test.
• LLM Wiki — Karpathy compiler 패턴. raw docs → structured wiki 컴파일.
• Thinking Process — 사용자 입력(L1/L2)을 L4까지 구체화하는 사전 등록된 분석 절차.

---

변경 이력

• 2026-04-16: thinking process 추가, SDD/RTM 업데이트 (pipeline 매핑, 검증 목적)
• 2026-04-16: 초판 — 5개 용어 (Constitution, SDD, RTM, L0-L4, LLM Wiki)

decisions.md

Design Decisions

claudie-workflow 의 설계 결정 색인. 한 줄 요약 + 필요 시 세부 파일 링크 (docs/decisions/NNN_*.md).

번호는 unique ID. 새 결정은 다음 번호로 추가. 뒤집힌 결정은 취소선 + 새 번호.

---

• 1. 레포 = github.com/redism/claudie-workflow (private). 작업 디렉토리 ~/dev/claudie-workflow.

• 002. 첫 sync 대상 = jeffrium-hub + dtonic. → 033 으로 대체. dit 트리는 claudie 정립 후 별도 마이그레이션 트랙.

• 3. 페르소나 = 클로디 (Claudie) — 오빠의 개인 비서 + 사고 파트너. 테토녀+애교, 자극제 원칙, 가설 표현 원칙. (../CLAUDE.md)
• 4. Phase-driven 작업 원칙 — 잘게 쪼갠 to-do X, 한 번에 통째 처리 X. 검증 가능한 phase 단위로 끊기. 의사결정은 phase 진입 전에 합의.
• 5. 4-track 자산 분류 = core / packages / repo-specific / excluded — core 강제 sync, packages opt-in, repo-specific 은 claudie 무관, excluded 는 런타임/캐시. (../catalog/v1.md)
• 6. Backend abstraction = Hybrid (옵션 D) — core 에 단일 commands + core/skills/issue-backend/ 추상화 + 📦 issue-{hub,jira,notion} 어댑터 패키지. capability provides: issue-backend, mutually exclusive.
• 7. claudie 자체의 issue backend = issue-hub — Hub Supabase 사용. claudie-workflow 작업은 Hub task 로 트래킹 (dogfooding).
• 8. adopt 모드 보류 — 첫 sync 대상 두 레포가 정렬되어 있어서 단순 overwrite + git diff 확인으로 충분.
• 9. speckit 미도입 — jeffrium-hub 는 functional spec 으로 독자 구축.
• 10. Claude Code plugin 시스템 대신 self-built — plugin 이 templates 배포 / settings.json hook 등록 / backend capability 추상화를 지원하지 않음. private dogfooding 단계라 marketplace 이점 제로. plugin 스펙과는 호환 가능하게 설계 (미래 이식 대비).
• 11. Remote update = LLM-mediated via consumer Claude 세션 — 기계적 복사 X. 각 consumer repo 에서 사용자가 /claudie update 호출 → 그 세션의 Claude 가 git log 를 읽어 변경 의도 이해 → 필요 시 confirm → 반영. 별도 Claude 인스턴스 스폰 X. (decisions/011_sync-paradigm.md)
• 12. Self-update loop = 기계적 복사 (sync-self.ts v0) — 같은 레포 내 core/ → .claude/. 편집 방향이 단일 (core 에서만) 이라 drift 없음. symlink 샷컷은 명시 거부 (sync 인프라 자체의 dogfooding 검증을 놓치기 때문).
• 13. Base reference = last_sync_sha 하나 — 3-way merge base 스냅샷 별도 저장 X. 이후 commit 들은 git log 로 읽어 분석. claudie-workflow 가 영원히 git 이라는 가정 위.
• 14. UX = push fan-out / wire = pull — 사용자 경험은 "편집 → 자동 전파" 처럼 느끼지만 실제 구현은 각 consumer 가 pull. non-blocking, fail-soft, 짧은 timeout.
• 15. SessionStart hook 의 역할 = 새 버전 감지만 — upstream commit 있는지 감지해서 한 줄 알림. 실제 update 는 사용자 수동 호출. LLM 호출은 hook 에 넣지 않음.
• 16. 머신 독립성 전제 — 누구나 claudie-workflow 접근 권한만 있으면 설치 후 동일 동작. 특정 개발자 머신의 로컬 경로 가정 금지.
• 17. Registry = 머신 로컬 clone — 각 머신이 claudie-workflow 의 git clone 을 둠 (가설 경로 ~/.claudie/registry/). 머신당 1개, 여러 consumer repo 가 공유.
• 18. .claudie.json manifest 로 트래킹 — {core_sha, packages, last_sync}. 경로 미확정 (.claude/ 아래 vs .claudie/ 아래).
• 19. CLI 인터페이스 = claudie install / sync / status / diff / graph / experiment — 이름과 서브커맨드 초안. Phase 1C 에서 확정.
• 20. SessionStart hook 자동 등록 (idempotent) — claudie install 이 consumer 의 .claude/settings.json 에 hook 을 idempotent 하게 추가. 마커로 식별. --no-hook opt-out.
• 21. c-epic 으로 claudie-workflow 자체의 Phase 관리 — Phase 1 작업을 c-epic 워크플로우로 관리. tasks/claudie-phase-1/ 워크스페이스. 자기 자신이 첫 검증 사례.
• 22. 시각화 로드맵 — command frontmatter (triggers, triggered_by, phase) → claudie graph → mermaid 자동 생성 → STATUS.md 에 임베드 → 궁극 Hub /workflows 페이지 react-flow.
• 23. 업데이트 채널 개념 (stable / beta / dev 등) — consumer 가 "어느 정도 안정된 버전까지 받을지" 선택 가능. 구현 가설: git tag / branch 기반 (stable = latest release tag, beta = main HEAD, dev = 특정 feature branch). manifest 의 channel 필드. 기본값 stable. claudie-workflow 자신은 dogfooding 이라 dev 또는 beta. 세부 스펙 미확정.
• 24. ralph-loop 확장 — 독립 감사 agent 패턴. 작업 LLM 과 별도로, 산출물 검증/리뷰를 수행하는 독립 agent 가 ralph-loop 안에서 동작. spec acceptance criteria 검증 + constitution check + 산출물 정합성 + 코드 리뷰를 통합. 통과할 때까지 세션 종료 차단. "독립 감사기관" 컨셉.
• 25. LLM attention 분산 방지 + 사기 방지 = 워크플로우 설계의 근본 목표. 수단: (a) output format 강제 (자유 형식 차단, 항목별 Result + Evidence), (b) constitution 체크리스트 (원칙별 위반 여부 명시적 체크 + 증거), (c) ralph-loop 확장 (024). promise-guard 가 이 원칙의 가장 단순한 구현.
• 26. Spec 구조 = granularity 별 분리 (L0 Vision → L1 Journey → L2 Feature → L3 Technical → L4 Test) + deps graph (frontmatter 기반 parent/children/tracks). L0 강제 (제품 비전 또는 프로젝트 핵심 방향성). 이슈번호 ≠ 스펙번호 (prefix 로 분리, 상호 참조). deps graph 원칙: 프로그램 검증 가능 + 시각화 가능 + LLM 이해 가능.
• 27. Spec lifecycle = planned (기획) → started (c-start) → evolve (작업 중) → confirmed (c-finalize + PR merge). as-is/to-be 분리. c-finalize 시 to-be → as-is 병합. "확정" = confirmed/decided, not absolute truth.
• 28. c-finalize 확장 = 기존 (코드 리뷰 + PR + 태스크 상태) + 산출물 정리 단계 추가 (tasks → docs 승격 제안, spec 병합, constitution check, acceptance criteria 검증). 사용자 리뷰 필수.
• 29. 문서 분류 핵심 축 = (a) 정제 수준 (raw → 정제됨 → 검증됨), (b) 가설 수준 (가설 → 검토됨 → confirmed). raw 가설은 tasks/, confirmed 정제는 docs/specs/. LLM Wiki 는 raw → wiki 컴파일 (별도 레포). "도메인 범위" 가 잠재적 세 번째 축.
• 30. 작업폴더 (tasks/) = 핵심 workbench. 대부분의 작업이 여기서 발생. raw material + 가설의 발원지. 이슈 없는 임시 작업은 tasks/_scratch/YYYY-MM-DD-{topic}/. c-start, c-epic 과 연계.
• 31. 문서 best-practice 구조 강제 — c-doc 커맨드가 scaffold + check + archive 를 수행. docs/ = 지식 자산 (evergreen), tasks/ = 행동 추적, meetings/ 과 reports/ = 운영 산출물. 오래된 문서는 archive (삭제 X) + 요약 stub.
• 32. Silent failure 금지 — 모든 실패에는 메시지가 있어야 함. fail-soft (세션 블로킹 X) 는 허용하되, silent fail (에러를 삼킴) 은 금지. hook, CLI, sync 모두 적용. 사용자가 "왜 안 됐지?" 를 추적할 수 있어야 함.
• 33. Walking skeleton 테스트 대상 = ahmo (1순위, submodule 구조 커버) + jeffrium-hub (2순위, 기존 워크플로우 migration path 검증). dtonic 은 Phase 1 이후. ahmo 는 Jira backend + 3개 submodule 로 다양한 구조 검증. jeffrium-hub 는 기존 .claude/ 자산이 풍부해서 migration path 자연스러운 제공 필수.
• 34. Consumer 측 claudie 명령어 = /claudie {subcommand} 단일 커맨드 — update, status 등을 arguments 로 라우팅. 파일: core/commands/claudie.md. /update-claudie 형태 폐기.
• 35. 외부 harness (orchestrator) 도입 (향후) — 단순 ralph-loop 을 넘어, 워크플로우 전체 프로세스를 강제하는 외부 orchestrator. 각 리뷰 단계 진행 강제 + "진짜 사용자를 호출해야 하는 상황인가" gatekeeper 역할. LLM 이 스스로 "사용자 승인 받았음" 이라고 넘어가는 것을 구조적으로 차단. ralph-loop (025) 의 상위 진화.
• 36. Self-contained 필수 원칙 — core track 에 들어가는 모든 자산(commands, agents, scripts, templates)은 반드시 self-contained 이어야 한다. 외부 파일 참조(다른 자산, 레포 특화 파일) 금지. 의존하는 다른 자산이 있으면 해당 의존성도 함께 core 에 포함하거나, 없을 때의 fallback 을 반드시 내장해야 한다. 자산 작성/수정 시 의존성 체크를 한 번에 수행할 것 — "나중에 고치자" 금지. 이 원칙 위반은 consumer repo 에서 silent failure 를 일으키므로 decision 032 와 직결.
• 38. claudie-workflow 의 핵심 목표 = LLM 의 병신짓을 구조적으로 차단 — "리뷰 승인 없이 다음 단계 진행", "검증 없이 완료 보고", "사용자 confirm 자가 승인" 같은 병신짓이 어떠한 경우에도 발생하지 않도록 harness 를 구축하는 것이 이 프로젝트의 존재 이유. prompt 지시만으로는 불충분 (Step 001 세션에서 동일 패턴 반복 증명됨). 외부 orchestrator (decision 035) 가 각 게이트에서 물리적으로 차단해야 함. 99.9% 신뢰도 목표.
• 54. decisions.md 작성 규칙 = 완전한 한 문장으로 항목을 남기되, 한 문장으로 논의 맥락이 충분히 전달되지 않으면 독립 문서(docs/decisions/NNN_xxx.md)에 상세 기록한다.
• 53. claudie-workflow 자체에 L0→L4 체인을 실제 구축(dogfooding)하고 그 과정에서 문제점을 발견·개선하는 방식으로 진행한다 — 이론적 설계 완성을 기다리지 않는다.
• 52. thinking process·디렉토리 구조 등 consumer repo 별 확장 메커니즘은 미래 계획으로 두고, 우선 claudie-workflow 에 맞는 opinionated 버전을 먼저 구축한다.
• 51. SDD의 specify/plan/tasks 파이프라인을 L0-L4에 대응시킨다 — 사용자 입력(L1/L2)을 thinking process로 구조화하여 L3→L4까지 구체화하며, 궁극적으로 c-epic start L4-010 한 번에 완료까지 가는 것이 비전이다. (상세)
• 50. L4 하나의 크기는 "LLM이 한 번에 완료할 수 있는 의미 있는 단위"로 하되, 너무 작으면 맥락 손실이 발생하므로 "DB 스키마 설계 완료"나 "API 엔드포인트 전체 구현" 수준을 기준으로 한다.
• 49. 사용자 입력이 들어오면 AI가 사전 등록된 thinking process 중 적합한 것을 추천하고 사용자가 confirm한다 — 자동화 모드에서는 AI가 직접 선택하며, 각 process는 별도 정의하고 핵심 산출물은 의미 있는 L4 목록이다.
• 48. 스펙의 children 필드는 우선 스크립트로 수동/check 시 자동 계산하고, 이후 edit hook으로 수시 갱신하는 방향으로 점진 자동화한다.
• 47. 스펙 파일은 docs/specs/ 아래 레벨별 하위 폴더(L0/, L1/, L2/, L3/, L4/)에 저장하며, 스펙이 많아지면 일부를 archive 할 수 있다.
• 46. L0 문서는 제품/프로젝트의 북극성과 핵심 원칙을 담되, L1을 기계적으로 도출하는 구조가 아닌 discussion 가이드 역할로 사용한다.
• 45. 스펙 lifecycle을 planned/done/discarded 3상태로 단순화한다 — "작성 중"은 별도 상태 없이 planned 문서에 내용이 채워지는 것으로 표현하고, 시간 흐름은 History 섹션이 기록한다. (상세)

• 027. → 045 로 대체.

• 44. 스펙 frontmatter에서 parent만 수동 관리하고 children은 스크립트가 자동 계산하며, staleness는 review_at 필드 대신 문서 내 History 섹션(로그 타입: created/reviewed/done/discarded/archived/note)으로 관리한다. (상세)
• 43. LLM 판단이 개입하는 L3 스펙도 동일한 Input/Process/Output 구조로 작성하고 L4 Test로 검증하되, 스펙대로 동작하지 않으면 코드 버그와 동일 취급하며 non-deterministic은 알려진 한계로 받아들인다.
• 42. 스펙 번호는 레벨 prefix 방식(L0-001, L2-007 등)을 사용하여 번호만으로 어떤 레벨인지 즉시 파악할 수 있게 한다.
• 41. Constitution 준수 여부는 Claude 자체의 self-check가 아닌 외부 체크리스트와 hooks로 검증한다(가설) — self-check는 실패율이 높으므로 미통과 시 다음 단계 진행을 물리적으로 거절하는 구조가 필요하다.
• 40. LLM이 실행 주체인 스펙은 "이런 입력(Input)을 주면 이런 프로세스(Process)를 거쳐 이런 출력 또는 행동(Output/Side-effect)을 한다"는 구조로 정의한다.
• 39. SDD 기반 L0-L4 워크플로우에 Data Dictionary 구축을 포함하여, LLM이 새 세션에서 프로젝트 용어를 멋대로 해석하는 것을 방지한다 — 파일: docs/data-dictionary.md.
• 37. SessionStart hook 자동 감지 보류 — hook 동작 불안정 (multi-line command 제한, stdout/stderr 전달 경로 불명확 등). 당분간 사용자가 /claudie update 를 수동 실행하는 방식으로 운영. hook 인프라는 코드로 남겨두되 install 시 등록하지 않음. 안정화되면 재도입.

---

미확정 / 다음 결정

• Q2' 판단 경계 — Claude 가 sync 중 어디까지 자동, 어디부터 confirm. /claudie update prompt spec 작성 시 dogfooding 경험으로 결정.
• Registry 경로 확정 — ~/.claudie/registry/ 가설 상태.
• bin/claudie 언어 — shell vs bun.
• drift 감지 v1 — self-update 의 "삭제된 파일 추적" 과 remote update 의 "local 변경 탐지".
• .claudie.json vs .claudie/config.json — 단일 파일 vs 디렉토리 경로.
• 채널 스펙 (023 세부) — 채널 개수? 전환 UX (claudie channel set beta?) 채널별 pull 대상 (tag/branch)? downgrade 허용?

l0-l4.md

L0-L4 (Spec Granularity Levels)

정의

Decision 026에서 정의된 스펙 granularity 계층. 각 레벨은 상위 레벨을 parent로 참조하며 RTM 추적성을 유지한다.

레벨 정의

L0 Vision — 제품/프로젝트의 핵심 방향성. 강제 (모든 프로젝트에 최소 1개). 다른 모든 스펙의 최상위 근거.

L1 Journey — 사용자 여정, 시나리오. "사용자가 X를 하면 Y가 일어난다" 수준의 흐름 기술.

L2 Feature — 기능 단위 스펙. L1 Journey를 구현하기 위해 필요한 개별 기능 정의.

L3 Technical — 기술 설계. API, 데이터 모델, 알고리즘, 프롬프트 스펙 등. LLM이 실행 주체인 경우: Input → Process → Output/Side-effect 구조 (decision 040).

L4 Test — 테스트 시나리오, acceptance criteria. Constitution 위반 검증 케이스를 반드시 포함.

Lifecycle (Decision 045, decision 027 대체)

planned → done | discarded

• planned: 이 스펙이 필요하다는 것은 확정. 내용은 비어있거나 작성 중일 수 있음.
• done: 리뷰 완료, 확정. 바꾸려면 새 스펙이나 amendment.
• discarded: 기능 제거 또는 방향 전환으로 폐기. RTM에서 "왜 사라졌는지" 추적용.

"작성 중" 별도 상태 불필요 — planned 문서에 내용이 채워지는 것 자체가 작성 중. 시간 흐름은 History 섹션이 기록.

Frontmatter 스키마 (Decision 042, 044)

---
id: L2-007
title: "로컬 drift 감지"
type: spec
level: L2
status: planned            # planned | done | discarded
parent: L1-002
related_decisions: [042, 044]
created: 2026-04-16
---

• parent만 수동 관리. children은 스크립트가 자동 계산.
• related_decisions로 decision 참조.

History 섹션 (Decision 044)

문서 하단에 History 섹션. 로그 타입:

• created — 문서 최초 생성 (scaffold 자동)
• reviewed — 리뷰/constitution check 통과
• done — planned → done 전환
• discarded — planned → discarded 전환
• archived — archive 처리
• note — 기타 (스펙 의미 변경, 참고사항 등. updated 대체)

확정된 사항

• 번호 체계: level prefix 방식 — L0-001, L1-003, L2-007 (decision 042)
• L3 형태: LLM 판단이 개입해도 동일한 Input/Process/Output 구조. 검증은 L4 Test. 스펙대로 안 되면 버그 취급 (decision 043)
• Lifecycle: draft → confirmed 2단계 (decision 045)
• Frontmatter: parent만 수동, children은 스크립트 자동 (decision 044)
• Staleness: review_at 필드 대신 History 섹션 (decision 044)
• L0: 북극성 + 원칙. Discussion 가이드 역할 (decision 046)

내가 아직 불확실한 부분

• frontmatter 필수 필드의 최종 스키마 (history log 타입 확정 필요)
• 한 L1에서 여러 L2가 나올 때의 관리 방식

llm-wiki.md

LLM Wiki

정의

Karpathy의 compiler 패턴 기반 지식 컴파일 레이어. Raw 문서를 LLM이 synthesis해서 structured wiki로 변환한다.

핵심: query-time이 아니라 ingest-time에 지능을 투입. 한 번 컴파일하면 읽기만 하면 됨.

Karpathy 원본 아키텍처

출처: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

raw/          ← 소스 문서 (papers, repos, datasets)
  ↓ LLM compile (사실 추출, 압축, 관계 식별)
wiki/         ← 컴파일된 결과물 (entity pages, concept pages, comparisons)
  index.md    ← 한 줄 요약 카탈로그 (LLM이 먼저 읽고 drill-down)

세 단계:

1. Ingest: raw materials 수집
2. Compile: LLM으로 사실 추출, 압축, 관계 식별
3. Active maintenance: "linting" pass로 일관성 유지

구현체에서 배운 구체적 패턴

llm-wiki-compiler (https://github.com/ussumant/llm-wiki-compiler)

• Two-phase pipeline: Phase 1에서 모든 concept 추출 → Phase 2에서 page 생성. 순서 의존성 제거.
• Incremental compilation: 해시 기반 변경 감지. 수정된 소스만 재컴파일.
• 분류: LLM이 새 문서를 "file this to our wiki"처럼 기존 구조에 배치.

DeepWiki (https://github.com/AsyncFuncAI/deepwiki-open)

• 코드 레포 → 위키 변환. RAG pipeline (스캔 → 벡터 DB → 시맨틱 검색).
• 다양한 LLM provider 지원.

공통 패턴

• Cross-references: YAML frontmatter + [[wikilinks]]
• Versioning: git-based — 각 업데이트가 diff로 추적 가능
• Scale: ~100 소스, 수백 페이지까지 동작. 그 이상은 index.md가 감당 못함.
• index.md: 전체 wiki의 한 줄 요약 카탈로그. LLM이 먼저 이걸 읽고 관련 page로 drill-down.

claudie-workflow와의 관계

• c-doc이 관리하는 raw docs (L0-L4 specs, decisions, DD 등) = LLM Wiki의 입력 소스
• c-doc이 강제하는 frontmatter/구조 = wiki compilation의 전제조건
• LLM Wiki 자체는 별도 private repo (decision 029)
• claudie의 sync 메커니즘 일부 재사용 가능 (README)

오빠가 결정한 사항 (decisions.md 기반)

• 별도 private repo로 분리 (decision 029, README)
• raw → wiki 컴파일 구조 (decision 029)
• "도메인 범위"가 잠재적 세 번째 분류 축 (decision 029)
• claudie와는 분리되지만 sync 메커니즘 일부 재사용 (README)

아직 미결정

• 구체적 형태 (markdown wiki? 웹 앱? 둘 다?)
• compilation 주기 (매 커밋? 수동? 스케줄?)
• 어떤 문서가 wiki 소스가 되고, 어떤 건 안 되는지의 기준
• "도메인 범위" 세 번째 축의 구체적 영향
• incremental compilation 도입 여부 (해시 기반 변경 감지)
• scale 제한 (~100 소스) 에 대한 대응 전략

참고 출처

• Karpathy 원본 gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
• llm-wiki-compiler: https://github.com/ussumant/llm-wiki-compiler
• DeepWiki: https://github.com/AsyncFuncAI/deepwiki-open
• LLM Wiki v2 extensions: https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2
• Thoughtworks SDD: https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices
• Addy Osmani — Spec for AI Agents: https://addyosmani.com/blog/good-spec/
• LLMs for Documentation Traceability: https://www.arxiv.org/pdf/2506.16440

rtm.md

RTM (Requirements Traceability Matrix)

정의

요구사항 레벨 간 추적 관계를 관리하는 체계. 모든 하위 스펙이 상위 스펙까지 거슬러 올라갈 수 있고, 역으로 상위에서 하위 구현/테스트까지 추적 가능해야 한다.

목적 — 빠뜨림/불일치 감지

RTM의 본질은 "빠진 것"과 "근거 없는 것"을 찾는 행위:

• Forward tracing (L0→L4): "이 요구사항에 대한 구현/테스트가 존재하는가?" — 기능을 정의했는데 테스트가 없으면 검증 불가
• Backward tracing (L4→L0): "이 코드/테스트는 왜 존재하는가?" — 근거 없는 구현은 scope creep
• Change impact: "L2 스펙이 바뀌면 어떤 L3/L4가 영향받는가?" — 상위 변경 시 하위 누락 방지

claudie-workflow에서의 RTM

L0-L4 계층 간 parent 링크로 구현 (decision 044):

L0 Vision
 └→ L1 Journey (parent: L0-001)
      └→ L2 Feature (parent: L1-001)
           └→ L3 Technical (parent: L2-001)
                └→ L4 Task/Test (parent: L3-001)

• parent: 수동 관리 (frontmatter)
• children: 스크립트가 parent 기반으로 자동 계산 (decision 044, 048)

검증 항목

spec-check 스크립트가 검증하는 것:

• orphan: parent가 존재하지 않는 스펙 → warning (존재할 수 있음)
• gap: done인 상위 스펙에 하위 스펙이 하나도 없음 → 빠뜨림 가능성
• cascade: 상위가 discarded인데 하위가 planned → 정리 필요

참고

RTM이라는 용어는 전통적 소프트웨어 공학에서 왔지만, claudie-workflow에서의 실질적 의미는 "L0-L4 parent/children 추적성 기반 빠뜨림/불일치 감지".

sdd.md

SDD (Spec Driven Development)

정의

정형화된 스펙을 코드보다 상위 권위(authoritative source)로 두는 개발 방법론. 코드는 스펙의 구현체. 스펙이 먼저 작성되고, 코드가 스펙을 따른다.

핵심 구성 요소

• Specification: 기능/기술 스펙 (L0-L4 계층)
• Constitution: 불변 원칙 (모든 스펙에 적용)
• Traceability: 스펙 간 추적성 (RTM)

SDD Pipeline → L0-L4 매핑 (Decision 051)

SDD의 표준 파이프라인과 claudie-workflow L0-L4의 대응:

SDD pipeline        L0-L4 매핑
───────────────     ──────────────────────
Constitution    →   L0 Vision + Constitution 원칙
specify         →   L1 Journey / L2 Feature
plan            →   L3 Technical
tasks           →   L4 Task/Test
implement       →   c-epic start L4-xxx

흐름: 사용자 입력(L1/L2 수준) → AI가 thinking process 추천(decision 049) → 사용자 confirm → L3/L4까지 구조화/구체화 → L4 단위로 실행.

궁극 비전: c-epic start L4-010 → ralph-loop 등을 통해 거의 한 방에 완료까지 진행 (decision 051).

LLM 워크플로우에서의 SDD

전통적 SDD는 프로그래머가 스펙을 읽고 코드를 작성. claudie-workflow에서는 LLM이 실행 주체이므로:

• 스펙 = LLM에게 주는 prompt의 구조화된 형태
• Constitution = LLM이 반드시 지켜야 하는 불변 규칙
• 검증 = 외부 체크리스트 + hooks (decision 041, 가설)

Decision 040: LLM 실행 스펙의 기본 구조 = Input → Process → Output/Side-effect Decision 043: LLM 판단이 개입해도 동일 구조. 스펙대로 안 되면 버그 취급.

접근 방식 (Decision 052, 053)

• Opinionated first: 확장 메커니즘은 미래. claudie-workflow에 맞는 버전 먼저.
• Dogfooding: 이론적 설계보다 실사용 기반 검증 우선. 실제 구축 → 문제 발견 → 개선.

참고 출처

• Wikipedia — Spec-driven development: https://en.wikipedia.org/wiki/Spec-driven_development
• Martin Fowler — SDD tools: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
• Microsoft — Spec-Driven Development with GitHub Spec Kit: https://developer.microsoft.com/blog/spec-driven-development-spec-kit
• GitHub Spec Kit: https://github.com/github/spec-kit
• Panaversity — SDD Constitution: https://agentfactory.panaversity.org/docs/General-Agents-Foundations/spec-driven-development/the-project-constitution

thinking-process.md

Thinking Process

정의

사용자 입력(L1/L2 수준)을 받아서 L4 Task/Test 목록까지 구조화/구체화하는 사전 등록된 분석 절차. 입력의 종류(UI, 백엔드, 인프라, full-feature 등)에 따라 서로 다른 process가 적용된다.

동작 방식 (Decision 049)

1. 사용자가 L1/L2 수준의 입력을 줌
2. AI가 사전 등록된 thinking process 중 적합한 것을 추천
3. 사용자가 confirm (자동화 모드면 AI가 선택)
4. 선택된 process에 따라 L3/L4까지 구체화
5. 산출물: 의미 있는 L4 목록

핵심 원칙

• 각 process는 별도 정의 (확장 가능)
• Opinionated first (decision 052): 우선 claudie-workflow에 맞는 기본 세트. 확장 메커니즘은 미래.
• 핵심 산출물 기준: 의미 있는 L4까지 만들어내는 것이 목표

초기 process 타입 (미확정, 예시)

ui-feature    — UI 컴포넌트 추가/변경
api-feature   — 백엔드 API 구현
infra         — 인프라/아키텍처 변경
full-feature  — 위 조합
refactor      — 리팩토링
workflow      — claudie 워크플로우 커맨드/스크립트

L4 granularity (Decision 050)

각 L4는 LLM이 한 번에 완료할 수 있는 의미 있는 단위:

• "DB 스키마 설계 완료"
• "API 엔드포인트 전체 구현"

너무 작으면 맥락 손실, 너무 크면 LLM 실패율 증가.