claudie-workflow Data Dictionary v2 — index + 개별 용어 파일

constitution.md

Constitution

정의

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

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

핵심 특성

• 개별 feature에 종속되지 않음 — 모든 스펙, 모든 구현에 적용
• 독립 에이전트가 수시로 체크리스트로 검증
• 하나라도 위반하면 다음 단계로 넘어갈 수 없음
• 세션, 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 컴파일.

---

변경 이력

• 2026-04-16: 초판 — 5개 용어 (Constitution, SDD, RTM, L0-L4, LLM Wiki)

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 027)

planned → started → evolve → confirmed

• planned: 기획 완료, 아직 구현 시작 안 함
• started: c-start로 작업 시작
• evolve: 작업 중, 내용이 변화하고 있음
• confirmed: c-finalize + PR merge 후 확정. as-is/to-be 병합 완료.

내가 아직 불확실한 부분

• 번호 체계: L2-003 처럼 level prefix를 붙이는지, 통합 번호를 쓰는지
• frontmatter 필수 필드의 구체적 스키마
• L3에서 LLM 실행 스펙의 구체적 형태 (decision 040의 Input/Process/Output을 어떻게 markdown으로 표현하는지)
• 한 L1에서 여러 L2가 나올 때의 관리 방식
• evolve 상태에서 스펙 변경의 거버넌스 (아무나 바꿀 수 있나? 리뷰 필요?)

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)

정의

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

claudie-workflow에서의 RTM

L0-L4 계층 간 parent/children 링크로 구현:

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

• Forward tracing: L0에서 출발해 하위로 — "이 비전을 실현하기 위한 모든 구현이 존재하는가?"
• Backward tracing: L4에서 출발해 상위로 — "이 테스트는 어떤 비전에서 비롯되었는가?"
• Gap detection: 상위 스펙은 있는데 하위 구현이 없으면 gap

구현 방식 (미확정)

• frontmatter의 parent/children 필드로 링크
• c-doc check가 추적성 검증 (orphan, gap 감지)
• 구체적 frontmatter 스키마는 Step 003 설계에서 확정 예정

내가 아직 불확실한 부분

• RTM을 markdown frontmatter만으로 충분히 표현할 수 있는지, 별도 매트릭스 문서가 필요한지
• 1:N 관계 관리 (L1 하나에 L2 여러 개) 시 children 필드가 커지는 문제
• RTM 시각화 방식 (mermaid? 별도 도구?)

sdd.md

SDD (Spec Driven Development)

정의

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

핵심 구성 요소

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

LLM 워크플로우에서의 SDD

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

• 스펙 = LLM에게 주는 prompt의 구조화된 형태
• Constitution = LLM이 반드시 지켜야 하는 불변 규칙
• 검증 = 독립 에이전트(ralph-loop)가 수행

Decision 040: LLM 실행 스펙의 기본 구조 = Input → Process → Output/Side-effect

내가 아직 불확실한 부분

• SDD에서 "스펙이 evolve하는 과정"의 구체적 프로세스 (decision 027에 lifecycle은 있지만 실무 패턴 부족)
• LLM이 실행 주체일 때 L3 Technical 스펙의 최적 형태
• Constitution check의 구체적 실행 메커니즘 (체크리스트 형태? agent prompt?)

참고 출처

• 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