╔════════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██╗██████╗ ██████╗ ██████╗ ║
║ ██║██╔══██╗██╔══██╗██╔══██╗ Information Design-Driven Development ║
║ ██║██║ ██║██║ ██║██║ ██║ ║
║ ██║██║ ██║██║ ██║██║ ██║ "What information exists?" ║
║ ██║██████╔╝██████╔╝██████╔╝ -- always the first question. ║
║ ╚═╝╚═════╝ ╚═════╝ ╚═════╝ v1.0.1 ║
║ ║
║ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ║
║ ║
║ ┌─────────────────────────┐ ┌─────────────────────────┐ ║
║ │ │ │ │ ║
║ │ INFORMATION │ │ AGENT │ ║
║ │ MODEL │──────────>│ HARNESS │ ║
║ │ │ │ │ ║
║ │ - Entity Catalog │ │ - Hook Enforcement │ ║
║ │ - Data Model │ │ - Drift Detection │ ║
║ │ - Business Rules │ │ - Auto Audit │ ║
║ │ - Domain Glossary │ │ - Version Tracking │ ║
║ │ │ │ │ ║
║ └─────────────────────────┘ └────────────┬────────────┘ ║
║ │ ║
║ v ║
║ ┌─────────────────────────┐ ║
║ │ │ ║
║ │ AI AGENT │ ║
║ │ (Constrained) │ ║
║ │ │ ║
║ │ Agent = Model │ ║
║ │ + Harness │ ║
║ │ │ ║
║ └─────────────────────────┘ ║
║ ║
╚════════════════════════════════════════════════════════════════════════════════════════╝
npm i -g id3-cli프로젝트에서 /id3-start를 실행하세요. IDDD 설치 상태를 자동 감지하고, 진행 대시보드와 함께 다음에 실행할 명령어를 안내합니다.
"어떤 정보가 존재하는가?"에서 시작하세요, "어떤 기능을 만들어야 하는가?"가 아닙니다.
IDDD는 정보 모델을 모든 소프트웨어 개발의 중심에 두는 개발 방법론이자 AI 에이전트 스킬 패키지입니다. 기술 선택이 이루어지기 전에 엄밀한 Entity 카탈로그, 데이터 모델, 비즈니스 규칙, 도메인 용어집을 먼저 구축함으로써, IDDD는 논리 모델 단계에서 애플리케이션 동작의 80%가 이미 정의되도록 보장합니다. 이후 정보 모델은 요구사항, API 계약, 화면 설계, 유효성 검사 규칙이 체계적으로 도출되는 생성 중심(generative center)이 됩니다.
이 패키지는 IDDD를 AI 에이전트 스킬, Harness Hook, 문서 템플릿 세트로 설치하여, 코딩 에이전트가 전체 개발 생명주기에 걸쳐 정보 우선(information-first) 원칙을 강제하도록 합니다.
대부분의 소프트웨어 프로젝트는 *"어떤 기능을 만들어야 하는가?"*라는 질문으로 시작하여 곧바로 구현에 착수합니다. IDDD는 이를 뒤집습니다. **"이 도메인에 어떤 정보가 존재하는가?"**에서 시작하며, 정보 모델을 명세의 한 섹션이 아니라 다른 모든 개발 산출물이 도출되는 **단일 진실 공급원(single source of truth)**으로 취급합니다.
- 정보 모델이 생성 중심이다. 모든 코드, API, UI, 테스트는 Entity 카탈로그와 데이터 모델에서 도출됩니다. 코드가 명세와 불일치하면, 명세가 우선합니다.
- Entity 우선 식별. 코드를 작성하기 전에 Entity를 식별하고 문서화해야 합니다. 새로운 기능은 "어떤 엔드포인트가 필요한가?"가 아닌 "어떤 Entity가 관련되는가?"에서 시작합니다.
- 데이터 모델 추적성. 코드베이스의 모든 컬럼, 제약 조건, Relationship은 Entity 카탈로그의 항목으로 추적 가능해야 합니다. 추적되지 않는 스키마 요소는 드리프트(drift)로 간주됩니다.
- 출력 우선 설계. 입력(폼, API)을 설계하기 전에 사용자가 보는 것(대시보드, 보고서, 목록)을 먼저 설계합니다. 출력 이미지가 정보 모델을 주도합니다.
- 비즈니스 규칙은 명시적이다. 모든 유효성 검사, 제약 조건, 도출 규칙은 BR-xxx 식별자로 등록됩니다. 코드에만 존재하는 규칙은 부채(debt)로 간주됩니다.
IDDD는 전통적인 3단계 데이터 모델링 프로세스를 소프트웨어 개발 단계에 직접 매핑합니다:
┌───────────────────────────────────────────┐ ┌───────────────────────────────────────────┐
│ Conceptual Model │ │ Requirements / Scope Definition │
│ "What information exists?" │────────>│ Entity identification, user stories │
└───────────────────────────────────────────┘ └───────────────────────────────────────────┘
│
v
┌───────────────────────────────────────────┐ ┌───────────────────────────────────────────┐
│ Logical Model │ │ API Contracts / Validation / Biz Logic │
│ "How is it structured?" │────────>│ 80% of behavior defined here │
└───────────────────────────────────────────┘ └───────────────────────────────────────────┘
│
v
┌───────────────────────────────────────────┐ ┌───────────────────────────────────────────┐
│ Physical Model │ │ Implementation Decisions │
│ "How is it stored/executed?" │────────>│ Technology choices, storage, deployment │
└───────────────────────────────────────────┘ └───────────────────────────────────────────┘
정보 모델의 각 요소는 자동으로 개발 산출물을 함의합니다:
| 정보 모델 요소 | 도출되는 산출물 |
|---|---|
| Entity 식별 | 요구사항 범위, 사용자 스토리 |
| Relationship & Cardinality | API 엔드포인트 구조, 네비게이션 |
| Attribute & 데이터 타입 | 폼 필드, 유효성 검사 규칙, DTO |
| 제약 조건 | 입력 유효성 검사, 타입 정의 |
| 파생 Attribute | 비즈니스 로직, 계산 규칙 |
| 상태 전이 | 워크플로우, 상태 관리 |
| 집계 / 관계 규칙 | 트랜잭션 경계, 일관성 규칙 |
논리 모델이 완성되면, 기술 선택이 이루어지기 전에 애플리케이션 동작의 80%가 이미 정의됩니다.
| 플랫폼 | 에이전트 시스템 | 멀티 에이전트 전략 |
|---|---|---|
| Claude Code | Claude Agent Teams | 피어 메시징, 독립 워크트리 |
| OpenAI Codex | Codex Agents SDK | MCP Server를 통한 핸드오프 패턴 |
| 요구사항 | 상세 |
|---|---|
| Node.js | 18+ (npm 또는 호환 패키지 매니저 포함) |
| Claude Code | Claude Max 멤버십 + Agent Teams 활성화 |
| OpenAI Codex | ChatGPT Plus 이상 (Pro/Business/Enterprise) |
Node.js 18+와 npm이 필요합니다. AI 플랫폼 구독은 사용하는 플랫폼에 따라 필요합니다.
npm i -g id3-cli글로벌 설치 시 두 개의 글로벌 스킬(/id3-start, /id3-clear)이 등록되어 모든 프로젝트에서 사용할 수 있습니다. 프로젝트에서 처음 /id3-start를 실행하면 IDDD 설치 여부를 자동 감지하고 다음 단계를 안내합니다.
| 옵션 | 설명 |
|---|---|
[target-dir] |
대상 디렉터리 (기본값: 현재 디렉터리 .) |
--no-symlink |
심볼릭 링크 대신 스킬 파일 복사 (Windows에서 유용) |
--platform |
플랫폼 강제 지정: claude, codex, 또는 all |
대상 디렉터리에 CLAUDE.md가 이미 존재하면, id3-cli가 다음과 같이 묻습니다:
"IDDD appears to be already installed. Overwrite? (y/N)"
┌── IDDD installed ─────────────────────────────────────────┐
│ │
│ Next steps: │
│ │
│ 1. Fill in steering/product.md │
│ 2. Run /id3-start to begin │
│ 3. Customize steering/data-conventions.md │
│ │
│ Global Skills (via npm i -g): │
│ ├── id3-start (Entry Point) │
│ └── id3-clear (Project Reset) │
│ │
│ Project Skills (per-project): │
│ ├── id3-identify-entities (Phase 0/1) │
│ ├── id3-design-information (Phase 2) │
│ ├── id3-design-ui (Phase 2.5) │
│ ├── id3-spawn-team (Phase 3-5) │
│ ├── id3-info-audit (Audit) │
│ └── id3-preview (Visual Preview) │
│ │
└───────────────────────────────────────────────────────────┘
npm i -g id3-cli 실행 후, 다음 전역 스킬이 시스템 전체에 설치됩니다:
~/.claude/skills-global/ 전역 스킬 (npm i -g로 설치)
├── id3-start/ IDDD 시작점
│ ├── SKILL.md
│ └── references/
│ ├── phase-guide.md Phase 라우팅 분류 체계
│ └── dashboard-template.md 진행 대시보드 형식
└── id3-clear/ 프로젝트 초기화
└── SKILL.md
/id3-start 실행 후 (또는 id3-cli init .), 프로젝트는 다음 구조를 갖게 됩니다:
your-project/
│
│ ===== 공통 (모든 플랫폼) =====
│
├── skills/ 스킬 원본 (단일 진실 공급원)
│ ├── id3-identify-entities/ Phase 0/1: Entity 식별
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── phase0-brownfield.md 기존 코드에서 역추출
│ │ └── phase1-greenfield.md 새 프로젝트를 위한 구조화 인터뷰
│ ├── id3-design-information/ Phase 2: 정보 구조화
│ │ ├── SKILL.md
│ │ └── references/
│ │ └── phase2-procedure.md 정제 절차
│ ├── id3-design-ui/ Phase 2.5: UI 설계 & 구현
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── step1-structure-derivation.md
│ │ ├── step2-visual-contract.md
│ │ ├── step3-gate-and-mockup.md
│ │ └── step4-implementation.md
│ ├── id3-spawn-team/ 멀티 에이전트 구현 디스패치
│ ├── id3-info-audit/ 엔트로피 감사 (드리프트 감지)
│ └── id3-preview/ 정보 모델 시각적 프리뷰
│
├── specs/ 정보 모델 산출물
│ ├── entity-catalog.md Entity 목록 + 요약 테이블
│ ├── data-model.md Mermaid ERD + 설계 결정사항
│ ├── ui-inventory.md 화면 목록 + 매핑 매트릭스
│ ├── ui-structure.md 화면 목록 + 네비게이션 (Phase 2.5)
│ └── ui-design-contract.md 디자인 토큰 + 컴포넌트 매핑 (Phase 2.5)
│
├── docs/ 지원 문서
│ ├── business-rules.md BR-xxx 색인된 비즈니스 규칙
│ ├── domain-glossary.md 용어 / 영문명 / 정의 / 비고
│ ├── info-debt.md 불일치 추적기
│ └── model-changelog.md Keep a Changelog 형식
│
├── steering/ 프로젝트 수준 규약
│ ├── product.md 제품 비전 & 범위 (사용자 작성)
│ └── data-conventions.md PK 전략, 네이밍, 타임스탬프 등
│
├── hooks/ Harness Hook 스크립트 (빌드된 JS 번들)
│ ├── iddd-schema-drift.js 스키마 드리프트 감지
│ ├── iddd-rule-check.js 비즈니스 규칙 추적
│ ├── iddd-auto-audit.js 자동 엔트로피 감사
│ ├── pre-commit Git Hook (schema-drift + rule-check)
│ └── post-commit Git Hook (auto-audit)
│
├── .iddd/ IDDD 내부 상태
│ ├── commit-count auto-audit 간격 카운터
│ └── preview/ 생성된 프리뷰 HTML
│
│ ===== 플랫폼: Claude Code =====
│
├── CLAUDE.md 리드 에이전트 컨텍스트 문서
├── .claude/
│ ├── settings.local.json Hook 등록 (init에 의해 주입)
│ ├── skills/ -> skills/ skills/ 원본에 대한 심볼릭 링크
│ └── hooks/
│ └── hook-config.json IDDD Hook 설정
│
│ ===== 플랫폼: OpenAI Codex =====
│
├── AGENTS.md 크로스 플랫폼 에이전트 지침
├── .agents/
│ └── skills/ -> skills/ skills/ 원본에 대한 심볼릭 링크
└── .codex/
└── hooks.json Codex Hook 설정
스킬 콘텐츠는 단일 정규 위치(skills/)에서 유지됩니다. 플랫폼별 경로(.claude/skills/, .agents/skills/)는 init CLI가 동적으로 생성하는 심볼릭 링크입니다. 이를 통해 모든 플랫폼에 걸쳐 단일 유지보수 지점을 확보합니다. Windows에서는 --no-symlink를 사용하여 복사본을 생성하세요.
╔══════════════════════════════════════════════════════════════════════════╗
║ IDDD WORKFLOW OVERVIEW ║
╚══════════════════════════════════════════════════════════════════════════╝
┌──────────────┐ ┌──────────────┐
│ │<--- dialog ----->│ │
│ User │ │ Lead Agent │
│ │ │ │
└──────────────┘ └──────┬───────┘
│
┌──────────────────┴──────────────────┐
│ │
v v
┌────────────────────┐ ┌────────────────────┐
│ Existing code? │ │ No existing code? │
└─────────┬──────────┘ └─────────┬──────────┘
│ │
v v
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
│ Phase 0: Reverse-Extract │ │ Phase 1: Structured Interview │
│ │ │ │
│ - Scan ORM / schema files │ │ "What information does │
│ - Extract entities │ │ your domain manage?" │
│ - Extract relationships │ │ - Identify core entities │
│ - Verification Interview │ │ - Discover relationships │
└────────────────┬─────────────────┘ └────────────────┬─────────────────┘
│ │
v v
┌─────────────────────────────────────────────────────┐
│ Entity Catalog Produced │
└─────────────────────────┬───────────────────────────┘
│
v
┌────────────────────────────────────────────────────────────────────┐
│ Phase 2: Information Design │
│ │
│ - Conceptual --> Logical model │
│ - Derive business rules (BR-xxx) │
│ - Register hooks + version headers │
└─────────────────────────────────┬──────────────────────────────────┘
│
v
┌────────────────────────────────────────────────────────────────────┐
│ Phase 2.5: UI Design (id3-design-ui) │
│ │
│ - Entity --> Screen auto-derivation │
│ - Visual design contract (tokens, components) │
│ - 7-Pillar gate + 3-level mockup preview │
│ - Agent Teams implementation + post-audit │
└─────────────────────────────────┬──────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────┐
│ /id3-spawn-team │
└─────────────────────────┬───────────────────────────┘
│
┌──────────────┴──────────────┐
│ │
v v
┌────────────────────────────────┐ ┌────────────────────────────────┐
│ Claude Code: Agent Teams │ │ Codex: Agents SDK │
│ │ │ │
│ ┌────────┐ ┌──────┐ ┌────┐ │ │ ┌──────────────────────────┐ │
│ │ spec │ │ impl │ │ qa │ │ │ │ Handoff Pattern │ │
│ └───┬────┘ └──┬───┘ └─┬──┘ │ │ │ via MCP Server │ │
│ │ │ │ │ │ └──────────────────────────┘ │
│ └── messaging ────┘ │ │ │
│ (peer-to-peer) │ │ spec -> impl -> qa │
│ │ │ (sequential handoff) │
└────────────────────────────────┘ └────────────────────────────────┘
팁: 처음에
/id3-start를 실행하면 현재 진행 상태와 다음 단계를 안내합니다. 이후에는 아래 개별 명령어를 직접 사용하세요.
Phase 0/1: Entity 식별:
/id3-identify-entities를 실행하세요. 에이전트가 기존 코드베이스가 있는지(브라운필드) 새로 시작하는지(그린필드)를 자동으로 감지한 후, 적절한 식별 플로우를 실행합니다.
Phase 2: 정보 설계:
/id3-design-information을 실행하세요. 에이전트가 개념 모델을 논리 모델로 정제하고, 비즈니스 규칙을 도출하며, 버전 헤더와 Hook 설정을 구성합니다.
Phase 2.5: UI 설계:
/id3-design-ui를 실행하세요. 에이전트가 Entity 카탈로그에서 화면 구조를 도출하고, 디자인 토큰으로 시각적 디자인 계약을 수립하며, 인터랙티브 목업 프리뷰와 함께 7-Pillar 품질 게이트를 실행한 후, Agent Teams를 생성하여 화면을 병렬 구현하고 사후 감사를 수행합니다.
Phase 3-5: Agent Teams를 통한 구현:
/id3-spawn-team을 실행하세요. 에이전트가 확정된 정보 모델을 읽고 전문 에이전트 팀(spec-generator, implementer, qa-reviewer)을 생성하여 시스템을 병렬로 구현합니다.
IDDD의 진입점입니다. 처음 한 번 실행하면 프로젝트 설정, 진행 대시보드, 다음 단계 안내를 제공합니다. 요청을 함께 전달하면 올바른 Phase 스킬로 라우팅합니다. 이후에는 안내받은 개별 명령어를 직접 사용하세요.
기능:
- 자동 설정: 현재 프로젝트에 IDDD가 설치되어 있는지 감지합니다 (
specs/entity-catalog.md+CLAUDE.md). 설치되지 않은 경우, 자동으로id3-cli init .를 실행하여 IDDD를 설정합니다. - 진행 대시보드: 각 Phase(Phase 0/1, Phase 2, Phase 2.5, Phase 3-5)의 완료 상태를 시각적 심볼(완료 체크마크, 진행 중 다이아몬드, 미시작 원)과 진행 바로 보여주는 Phase 파이프라인을 표시합니다.
- 의도 라우팅: 요청을 함께 전달하면 올바른 Phase 스킬(
/id3-identify-entities,/id3-design-information,/id3-design-ui,/id3-spawn-team,/id3-info-audit, 또는/id3-preview)로 라우팅합니다. - 모호한 요청 처리: 요청이 여러 Phase에 매칭될 수 있는 경우(예: "목록에 필터 추가": UI 변경만인지 새 데이터 Entity가 필요한지), 라우팅 전에 명확화 질문을 합니다.
- UI 빠른 경로: 요청이 명시적 UI 키워드만 포함하고 데이터 모델이 이미 존재하는 경우(version >= 1.0), Entity 질문 없이 직접
/id3-design-ui로 라우팅합니다. - 전제 조건 확인: 대상 Phase의 전제 조건이 충족되지 않으면 경고하고 올바른 시작 Phase를 제안합니다.
사용법:
/id3-start 대시보드 표시 + 다음 명령어 안내
설치: npm i -g id3-cli로 ~/.claude/skills-global/id3-start/에 전역 설치됩니다.
IDDD 워크플로우의 진입점입니다. 이 스킬은 브라운필드와 그린필드 경로를 자동으로 분기합니다.
자동 감지 로직: 스킬은 프로젝트 루트에서 ORM/스키마 파일(Prisma, Drizzle, Django models, TypeORM entities, SQL migrations, Sequelize configs)을 스캔합니다. 발견되면 Phase 0으로 진입하고, 그렇지 않으면 Phase 1로 진입합니다.
기존 코드베이스의 경우, 에이전트가 4개 레이어에서 암묵적 정보 모델을 체계적으로 추출합니다:
| 레이어 | 소스 | 조사 대상 | 신뢰도 |
|---|---|---|---|
| L1 | DB 스키마 | 테이블, 컬럼, FK, 인덱스, 제약 조건 | 최고 |
| L2 | ORM / 모델 | 가상 필드, 파생 Attribute, 소프트 삭제, 상태 | 높음 |
| L3 | API 계약 | 엔드포인트, DTO, 유효성 검사 로직 | 중간 |
| L4 | 프론트엔드 | 라우트, 컴포넌트, 폼 필드 | 참고 |
L4 조사는 철저합니다: 파일 기반 라우팅(Next.js app/, pages/), React Router, Vue Router 등을 스캔하여 화면-Entity 매핑 매트릭스가 포함된 완전한 UI 인벤토리(specs/ui-inventory.md)를 구축합니다.
발견 사항은 일치(레이어 간 일관성 있음), 불일치(docs/info-debt.md에 기록), 암묵적(코드 로직에 숨겨져 있던 것을 명시적 비즈니스 규칙으로 도출)으로 분류됩니다.
추출 후, 검증 인터뷰를 통해 사용자와 정확성을 확인합니다.
생성되는 산출물: specs/entity-catalog.md, specs/data-model.md, specs/ui-inventory.md, docs/business-rules.md, docs/info-debt.md
새 프로젝트의 경우, 에이전트가 도메인 정보를 발견하기 위한 구조화 인터뷰를 수행합니다:
- 정보 식별: "이 시스템이 관리하는 핵심 '사물'(명사)은 무엇입니까?"
- Relationship 발견: "이것들은 어떻게 관련됩니까? 일대다입니까, 다대다입니까?"
- 규칙 발견: "어떤 규칙이 강제되어야 합니까? 상태 전이가 있습니까?"
- Silverston 범용 패턴 체크리스트: 에이전트가 발견된 Entity를 검증된 패턴과 대조합니다: Party, Product/Service, Order/Transaction, Classification, Status/Lifecycle, Hierarchy, Contact Mechanism, Document/Content.
생성되는 산출물: specs/entity-catalog.md, specs/data-model.md, docs/business-rules.md
개념 모델을 논리 모델로 정제합니다. 비즈니스 규칙, 유효성 제약 조건, 도출 규칙이 정보 모델에서 자동으로 도출됩니다.
전제 조건: specs/entity-catalog.md에 최소 2개의 식별된 Entity가 존재해야 합니다.
절차:
- Attribute 정제: 구체적인 데이터 타입(UUID, TEXT, INTEGER, TIMESTAMP, JSONB 등), NOT NULL / DEFAULT / UNIQUE 제약 조건, 인덱스 요구사항을 할당합니다.
- Relationship 구체화: FK 배치, 삭제/갱신 규칙(CASCADE, SET NULL, RESTRICT)을 결정하고, 다대다 Relationship을 위한 연결 테이블을 식별합니다.
- 자동 비즈니스 규칙 도출:
- NOT NULL 제약 조건 --> "이 필드는 필수입니다" (BR-xxx)
- UNIQUE 제약 조건 --> "중복이 허용되지 않습니다" (BR-xxx)
- FK + CASCADE --> "부모를 삭제하면 자식도 삭제됩니다" (BR-xxx)
- 상태 전이 --> "허용되는 전이 경로" (BR-xxx)
- 파생 Attribute --> "계산 규칙" (BR-xxx)
- 설계 결정 질문: 에이전트가 대용량 데이터 저장 전략, 소프트 삭제 범위, 멀티 테넌시, 감사 추적 필요성 등에 대해 사용자에게 질문합니다.
- 산출물 확정: 모든 명세 파일을 버전 헤더와 Hook 설정으로 업데이트합니다.
갱신되는 산출물: specs/entity-catalog.md, specs/data-model.md, docs/business-rules.md
정보 모델에서 UI 구조와 시각적 디자인을 도출한 후, Agent Teams를 사용하여 화면을 구현합니다.
전제 조건: Phase 2 완료 (entity-catalog.md version >= "1.0").
4단계 파이프라인:
- UI 구조 도출: 9개의 도출 규칙(entity -> list/detail/form/dashboard)을 사용하여 Entity를 화면에 자동 매핑합니다. 12개의 타입 기반 규칙으로 Attribute를 Widget에 매핑합니다. "출력 우선, 입력 후순위" 원칙을 적용합니다.
- 시각적 디자인 계약: 기존 프론트엔드 프레임워크(React, Vue, Svelte 등)와 UI 라이브러리를 감지합니다. 5개 디자인 토큰 영역(spacing, typography, color, copywriting, component registry)을 수립합니다.
- 구현 전 게이트: 7-Pillar 검증(구조 완전성, spacing, typography, color, copywriting, component registry, traceability)을 실행합니다. 샘플 데이터로 3단계 HTML 목업(wireframe, styled, interactive)을 생성합니다.
- 구현 + 사후 감사: Agent Teams를 생성하여 화면을 병렬 구현합니다. 구현 후 시각적 감사가 각 Pillar를 1-4로 점수화하고 상위 3개 수정 사항을 도출합니다.
산출물: specs/ui-structure.md, specs/ui-design-contract.md, .iddd/preview/mockup-*.html, .iddd/preview/ui-audit.html
확정된 정보 모델을 기반으로 시스템을 구현할 전문 에이전트 팀을 생성합니다.
전제 조건: specs/entity-catalog.md와 specs/data-model.md가 존재하고 Phase 2가 완료되어야 합니다.
세 명의 팀원이 생성되며, 각각 독립적인 컨텍스트 윈도우와 독립적인 Git 워크트리를 갖습니다:
| 팀원 | 역할 |
|---|---|
| spec-generator | 정보 모델을 requirements.md와 api-contracts.md로 변환 |
| implementer | 명세로부터 코드를 빌드, Entity당 하나의 원자적 커밋 |
| qa-reviewer | 정보 모델 대비 구현을 검증; 실패 시 implementer에게 직접 메시지 전송 |
작업 생성 규칙:
- Entity 카탈로그를 읽어 Entity별로 하나의 작업을 생성합니다 (모델 + 마이그레이션 + API + 유효성 검사 + 테스트).
- 데이터 모델의 FK 의존성이 의존성 그래프를 결정합니다.
- 독립적인 Entity는 병렬로 실행되고, 의존적인 Entity는 부모를 기다립니다.
Codex에서는 멀티 에이전트 작업이 Agents SDK 핸드오프 패턴을 사용합니다. Codex는 MCP Server(codex --mcp-server)로 시작되며, 프로젝트 매니저 에이전트가 Entity 카탈로그를 읽어 동일한 세 역할(spec-generator, implementer, qa-reviewer)에 핸드오프를 통해 작업을 분배합니다.
정보 모델 대비 코드베이스를 감사하여 드리프트와 엔트로피를 감지합니다.
절차:
specs/entity-catalog.md에서 Entity 목록을 읽습니다.- 코드베이스에서 다음을 스캔합니다:
- 미구현 Entity / 미정의 모델
docs/business-rules.md의 비즈니스 규칙이 코드에 반영되지 않은 경우- 데이터 타입 / 제약 조건 불일치
specs/ui-structure.md와specs/ui-design-contract.md대비 UI 일관성을 확인합니다:- 미구현 화면 / 미정의 화면
- 폼 필드 대 Attribute 매핑 불일치
- 누락된 네비게이션 경로
- 버전 헤더(
last_verified,audit_status)를 갱신합니다. - Hook 우회 이력(
.iddd/skip-history.log)을 확인합니다. - Entity별 상태 보고서를 시각적 지표와 함께 출력합니다.
시각적 출력: 감사 결과는 .iddd/preview/audit-{date}.html에 인터랙티브 HTML 대시보드로 렌더링됩니다.
정보 모델과 감사 결과를 브라우저에서 볼 수 있도록 경량 로컬 HTTP 서버를 시작합니다.
서버는 listen(0) (OS 할당 포트)을 사용하며 다음을 제공합니다:
- ERD 프리뷰: Entity 클릭 시 카탈로그 상세로 이동하는 인터랙티브 Mermaid ERD
- UI 목업:
specs/ui-structure.md와specs/ui-design-contract.md에서 도출된 와이어프레임 레이아웃 - 감사 대시보드: 비즈니스 규칙 커버리지가 포함된 Entity별 상태 카드
모든 HTML 파일은 .iddd/preview/에 유지되며, 서버 없이도 브라우저에서 직접 열 수 있습니다.
현재 프로젝트에서 IDDD가 생성한 모든 파일을 안전하게 제거하여, IDDD 설치 이전 상태로 복원합니다.
절차:
- 설치 확인: 프로젝트에 IDDD 파일이 존재하는지 확인합니다. 없으면 "IDDD 파일을 찾을 수 없습니다"라고 보고하고 중단합니다.
- 삭제 대상 스캔: 어떤 IDDD 디렉터리(
specs/,docs/,steering/,hooks/,skills/,.claude/skills/,.claude/hooks/,.codex/skills/,.agents/skills/,.iddd/)와 파일(CLAUDE.md,AGENTS.md)이 실제로 존재하는지 식별합니다. - 경고 표시: 삭제될 모든 파일과 디렉터리의 상세 목록을 표시합니다. 사용자 작성 파일(
steering/product.md,steering/data-conventions.md)에 대해서는 특별 주석을 추가합니다. - 확인 요구:
[y/N]으로 프롬프트합니다 (기본값 N). 명시적으로 "y" 또는 "yes"를 입력한 경우에만 진행합니다. - 삭제 실행: 식별된 대상만 제거합니다. 삭제 수량이 포함된 완료 요약을 표시합니다.
안전 규칙:
- 알려진 IDDD 파일 목록 이외의 파일은 절대 삭제하지 않음
rm -rf *같은 글로브 패턴을 절대 사용하지 않음- 확인 단계를 절대 건너뛰지 않음
- 선택적 삭제가 필요하면 수동 파일 작업을 사용하세요
설치: npm i -g id3-cli로 ~/.claude/skills-global/id3-clear/에 전역 설치됩니다.
IDDD는 자동화된 Hook을 통해 정보 우선 원칙을 강제합니다. 철학은 "프로세스를 따라주세요"가 아니라 **"따르지 않으면 커밋이 차단됩니다."**입니다.
| Hook | 트리거 | 동작 | 심각도 |
|---|---|---|---|
| schema-drift | pre-commit | 스키마 변경이 entity-catalog.md와 일치하는지 검증 | BLOCK (커밋 거부) |
| rule-check | pre-commit | 새 유효성 검사 로직이 business-rules.md에 있는지 확인 | WARN (커밋 허용, 메시지 표시) |
| auto-audit | post-commit | N번 커밋마다 info-audit 실행 | INFO (보고서 생성) |
스키마 관련 파일(Prisma, Drizzle, Django models, TypeORM entities, SQL migrations 등)을 수정할 때, Hook이 specs/entity-catalog.md도 함께 업데이트되었는지 확인합니다. 업데이트되지 않았으면 커밋이 거부됩니다. 정보 모델은 항상 코드보다 먼저 업데이트되어야 합니다.
모니터링 파일 패턴 (설정 가능):
prisma/schema.prisma, drizzle/**/*.ts, **/migrations/*.sql,
**/models.py, **/entities/*.ts, **/entities/*.java, schema.sql
유효성 검사 로직(Zod, Yup, Joi, Pydantic 등)을 추가하거나 수정할 때, Hook이 docs/business-rules.md에 대응하는 BR-xxx 항목이 있는지 확인합니다. 없으면 경고가 발생합니다. 커밋은 진행되지만, 누락된 규칙이 표시됩니다.
모니터링 파일 패턴 (설정 가능):
*.schema.ts, *.validator.*, **/validators/**
N번 커밋마다 (기본값: 10, 설정 가능), Harness가 코드베이스를 정보 모델과 비교하는 info-audit을 자동으로 실행합니다. 커밋 카운터는 .iddd/commit-count에 저장됩니다. 결과는 .iddd/preview/audit-{date}.html에 기록됩니다.
모든 Hook 설정은 .claude/hooks/hook-config.json (Claude Code) 또는 .codex/hooks.json (Codex)에 있습니다.
{
"enabled": true,
"hooks": {
"pre-commit": {
"schema-drift": {
"enabled": true,
"severity": "block",
"monitored_patterns": [
"prisma/schema.prisma",
"drizzle/**/*.ts",
"**/migrations/*.sql",
"**/models.py",
"**/entities/*.ts",
"**/entities/*.java"
]
},
"rule-check": {
"enabled": true,
"severity": "warn",
"validation_patterns": [
"*.schema.ts",
"*.validator.*",
"**/validators/**"
]
}
},
"post-commit": {
"auto-audit": {
"enabled": true,
"interval_commits": 10
}
}
}
}모든 IDDD Hook을 비활성화하려면 최상위의 "enabled"를 false로 설정하세요. 개별 Hook을 비활성화하려면 해당 Hook의 "enabled"를 false로 설정하세요. auto-audit 빈도를 변경하려면 "interval_commits"를 조정하세요.
IDDD_SKIP_HOOKS=1을 설정하면 모든 Hook을 일시적으로 건너뜁니다. 우회 기록은 .iddd/skip-history.log에 남으며, 감사 시 검토됩니다.
시간이 지나면 정보 모델과 코드가 괴리됩니다. IDDD는 세 가지 메커니즘으로 엔트로피에 대응합니다:
specs/entity-catalog.md와 specs/data-model.md에는 모델 상태를 추적하는 YAML 프론트매터가 포함되어 있습니다:
---
version: "1.0"
last_verified: "2026-04-05"
phase: "Phase 2 Complete"
entity_count: 12
rule_count: 19
audit_status: "clean"
---규칙:
version은 각 Phase 완료 시 증가합니다 (Phase 1:"0.1", Phase 2:"1.0", 이후:"1.1","1.2", ...).last_verified는 모델이 감사되거나 검증될 때마다 갱신됩니다.last_verified가 7일 이상 경과하면, 에이전트가 새 작업을 진행하기 전에/id3-info-audit실행을 권유합니다. 오래된 모델은 드리프트를 유발합니다.
모든 모델 변경은 Keep a Changelog 형식으로 docs/model-changelog.md에 기록됩니다:
## [1.0] -- 2026-04-05
### Phase 2 Complete
- 12 entities finalized in logical model
- 19 business rules derived
- Design decisions: D-01 (S3 separation), D-02 (multi-tenant reservation), D-03 (soft delete scope)
- UI proposals: 6 screens generatedauto-audit Hook(post-commit)은 N번 커밋마다 전체 정보 감사를 실행하여, 드리프트가 누적되기 전에 포착합니다.
IDDD는 프로젝트의 규약에 맞게 적응할 수 있도록 설계되었습니다. 커스터마이징 항목과 편집할 파일은 다음과 같습니다:
| 커스터마이징 항목 | 편집할 파일 |
|---|---|
| 제품 비전 & 범위 | steering/product.md |
| 네이밍 규약, PK 전략, 타임스탬프, 소프트 삭제 정책, ENUM vs 참조 테이블 | steering/data-conventions.md |
| Entity 정의 | specs/entity-catalog.md |
| 데이터 모델 (ERD) | specs/data-model.md |
| 비즈니스 규칙 | docs/business-rules.md |
| 도메인 용어집 | docs/domain-glossary.md |
| UI 화면 인벤토리 | specs/ui-inventory.md |
| UI 구조 (화면 도출) | specs/ui-structure.md |
| UI 디자인 계약 (토큰, 컴포넌트) | specs/ui-design-contract.md |
| Hook 동작 (활성화/비활성화, 심각도) | .claude/hooks/hook-config.json |
| Hook 모니터링 파일 패턴 | .claude/hooks/hook-config.json |
| auto-audit 커밋 간격 | .claude/hooks/hook-config.json |
| Codex Hook 설정 | .codex/hooks.json |
팁: 모든 specs/와 docs/ 파일은 버전 헤더가 포함된 YAML 프론트매터를 사용합니다. IDDD Harness는 이 버전을 추적하여 엔트로피 드리프트를 감지합니다. 명세 파일을 수정할 때는 항상 버전 헤더를 업데이트하세요.
$ npm i -g id3-cli
$ mkdir my-saas && cd my-saas && git init
$ claude
> /id3-start SaaS 도메인의 Entity를 식별해줘
╔════════════════════════════════════════════════════════════════╗
║ Welcome to IDDD -- Information Design-Driven Development. ║
║ Your information model is your harness. ║
╚════════════════════════════════════════════════════════════════╝
IDDD is not set up in this project. Setting up now...
IDDD initialized. Here is your project dashboard:
(대시보드에 모든 Phase가 ○ -- 미시작으로 표시)
Routing to /id3-identify-entities -- 구조화 인터뷰를 통해 도메인 Entity를 식별합니다.
이 Phase에서 생성되는 산출물: specs/entity-catalog.md, specs/data-model.md, docs/business-rules.md
Agent: "시스템이 관리하는 핵심 '사물'은 무엇입니까?"
You: "Users, Organizations, Subscriptions, Invoices, Features"
Agent: "Users와 Organizations는 어떻게 관련됩니까?"
You: "role Attribute를 가진 Membership Entity를 통한 다대다 관계입니다."
...
Entity catalog produced: specs/entity-catalog.md (5 entities, 7 relationships)
> /id3-design-information
개념 모델을 논리 모델로 정제합니다.
Agent refines attributes, derives 14 business rules.
specs/entity-catalog.md updated (version: 1.0)
docs/business-rules.md updated (BR-001 through BR-014)
> /id3-design-ui
정보 모델에서 UI를 도출하고 구현합니다.
Step 1: Deriving UI structure from 5 entities... 8 screens mapped
Step 2: Design contract established (React + Tailwind detected)
Step 3: 7-Pillar gate passed. Mockup preview: http://localhost:52341
Step 4: Spawning Agent Teams for screen implementation...
Post-audit: all 7 pillars scored 3+/4
specs/ui-structure.md generated
specs/ui-design-contract.md generated
> /id3-spawn-team
Agent Teams를 생성하여 병렬 구현합니다.
Spawning Agent Teams:
- spec-generator: generating requirements.md, api-contracts.md
- implementer: building User -> Organization -> Membership -> ...
- qa-reviewer: verifying against information model
$ cd existing-django-project
$ id3-cli init .
Detected: Django models (models.py), PostgreSQL migrations
IDDD installed.
$ claude
> /id3-identify-entities
Phase 0 (Brownfield) activated.
Scanning L1 (DB schema)... 23 tables found
Scanning L2 (Django models)... 19 models found
Scanning L3 (API contracts)... DRF serializers analyzed
Scanning L4 (Frontend)... React routes mapped
Discrepancies found:
- 4 tables have no corresponding Django model (logged in info-debt.md)
- 3 implicit business rules surfaced from view logic
Agent: "Does this information model accurately reflect your codebase?"
You: "Yes, but the legacy_audit table is deprecated -- remove it."
Entity catalog produced: 19 entities, 11 info-debt items
> /id3-design-information
Refining existing model...
New business rules derived from Django validators: BR-015 through BR-023
> /id3-design-ui
Step 1: Deriving UI structure... comparing with existing ui-inventory.md
Change summary: 2 new screens proposed, 3 existing screens updated
Step 2-4: Design contract, gate, and implementation...
IDDD는 여러 지적 전통의 아이디어를 종합합니다:
- Peter Chen의 ER Model (1976): "현실 세계는 Entity와 Relationship으로 구성된다." 정보 구조가 애플리케이션 로직에 선행한다는 근본적 통찰.
- Len Silverston의 Universal Data Models: 발견된 Entity를 검증하는 체크리스트 역할을 하는 재사용 가능한 정보 패턴(Party, Product, Order, Hierarchy).
- Eric Evans의 Domain-Driven Design (2003): Bounded Context, Ubiquitous Language, Aggregate 패턴. IDDD는 도메인 언어와 명시적 경계에 대한 강조를 계승합니다.
- Sophia Prater의 OOUX (Object-Oriented UX): "인터랙션보다 객체를 먼저 설계하라." ORCA 프레임워크(Objects, Relationships, CTAs, Attributes)가 IDDD의 출력 우선 UI 도출에 직접 영향을 미칩니다.
- Jamie Lord의 "Data First, Code Second" (2024): "지식을 데이터에 접어 넣어라." Unix 표현 규칙을 현대 소프트웨어 개발에 적용.
- Mitchell Hashimoto의 Harness Engineering (2026):
Agent = Model + Harness. AI 에이전트가 시간이 지나도 효과적으로 유지되려면 아키텍처적 제약, 컨텍스트 엔지니어링, 엔트로피 관리가 필요하다는 통찰. IDDD의 Hook 시스템, 버전 헤더, auto-audit은 Harness Engineering 원칙의 직접적 적용입니다.
핵심 통찰: 논리 모델이 완성되면, 기술 선택이 이루어지기 전에 애플리케이션 동작의 80%가 이미 정의됩니다. 그리고 그 정보 모델 자체가 AI 에이전트를 위한 최고의 Harness입니다.
MIT
┌──────────────────────────────────────────────────────────────────┐
│ │
│ "What information exists?" -- always the first question. │
│ │
└──────────────────────────────────────────────────────────────────┘