# ITDA **차세대 스펙 주도 개발 도구** [![npm version](https://badge.fury.io/js/itda-sdd.svg)](https://www.npmjs.com/package/itda-sdd) [![npm downloads](https://img.shields.io/npm/dm/itda-sdd.svg)](https://www.npmjs.com/package/itda-sdd) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) [English](README.md) | [한국어](README.ko.md) | [문서](docs/) | [npm](https://www.npmjs.com/package/itda-sdd)
--- > 🤖 **7개의 AI에이전트** × 📋 **27개의 전문 스킬** × ⚖️ **헌법(Consititution) 거버넌스** ITDA(잇다)는 6개의 주요 프레임워크에서 핵심 장점을 통합한, 포괄적인 **스펙 주도 개발(SDD)** 프레임워크입니다. 여러 AI 코딩 에이전트에 대응하는 프로덕션(실서비스) 대응 도구입니다. ## ✨ 왜 ITDA인가? | 과제 | ITDA의 솔루션 | | ------------------ | -------------------------- | | 🔀 AI 도구의 파편화 | **7 에이전트, 하나의 통합 워크플로** | | 📝 모호한 요구사항 정의 | **5가지 EARS 형식 패턴** | | 🔍 추적성(트레이서빌리티) 상실 | **요구사항→설계→코드→테스트 100% 추적** | | ⚠️ 품질 불일치 | **9개 헌법 조항 + Phase-1 게이트** | | 🔄 기존 프로젝트의 난제 | **차분 사양 + 변경 관리** | ## 🚀 퀵 스타트 ```bash # 30초로 설치 & 초기화 npx itda-sdd init # 기존 프로젝트용 - 자동 분석 및 스티어링 문서 생성 npx itda-sdd onboard # 완료! AI 에이전트에서 SDD 커맨드를 사용: # Claude Code: /sdd-requirements, /sdd-design, /sdd-implement # GitHub Copilot: #sdd-requirements, #sdd-design, #sdd-implement ```
기타 설치 옵션 ```bash # 전역 설치 npm install -g itda-sdd # 특정 AI 에이전트용으로 초기화 itda init --copilot # GitHub Copilot itda init --cursor # Cursor IDE itda init --gemini # Gemini CLI itda init --codex # Codex CLI itda init --qwen # Qwen Code itda init --windsurf # Windsurf IDE ```
--- ## 📊 v7.0.0 신규 기능 ### SDD 문서 경로 통합 📂 문서 유형을 **완전히 분리**하여 구조를 정리하고 명확성을 강화했습니다. ### 리뷰 게이트 엔진(Review Gate Engine) 각 개발 단계에서 **체계적인 리뷰**를 수행하기 위한 새로운 품질 게이트를 도입했습니다. #### 스토리지 구조 | 문서 유형 | 저장 위치 | 파일명 패턴 | |----------|-----------|-------------| | **요구사항 정의서** | `storage/specs/` | `{feature}-requirements.md` | | **설계서** | `storage/design/` | `{feature}-design.md` | | **태스크** | `storage/tasks/` | `{feature}-tasks.md` | | **검증 리포트** | `storage/validation/` | `{feature}-validation-report.md` | ``` storage/ ├── specs/ # 요구사항 정의서 전용 │ └── auth-requirements.md ├── design/ # 설계서 전용 │ └── auth-design.md ├── tasks/ # 태스크 전용 │ └── auth-tasks.md └── validation/ # 검증 리포트 └── auth-validation-report.md ``` #### 리뷰 게이트 | 게이트 | 설명 | 프롬프트 | |------|------|----------| | **Requirements Gate** | EARS 형식, 우선순위, 인수 기준 검증 | `#sdd-review-requirements` | | **Design Gate** | C4 모델, ADR, 컴포넌트 설계 검증 | `#sdd-review-design` | | **Implementation Gate** | 코드 품질, 테스트 커버리지, 네이밍 규칙 검증 | `#sdd-review-implementation` | | **Full Review** | 모든 게이트를 순차적으로 실행 | `#sdd-review-all` | ```bash # AI 에이전트에서 리뷰 프롬프트 사용 #sdd-review-requirements user-auth #sdd-review-design user-auth #sdd-review-implementation user-auth ``` #### 워크플로 대시보드 - 진행 상황 가시화: 5단계의 실시간 진행 상태 표시 - 블로커 관리: 블로커 추가·해결·추적 - 전이 기록: 단계 간 전이 기록 및 분석 - 스프린트 계획: 벨로시티 추적이 포함된 태스크 우선순위화 ```bash itda dashboard show # 워크플로 상태 표시 itda dashboard start # 신규 워크플로 시작 itda dashboard blocker # 블로커 관리 ``` #### 트레이서빌리티 시스템 - 자동 추출: 코드·테스트·커밋에서 ID 자동 추출 - 갭 탐지: 설계·구현·테스트 누락 요소 탐지 - 매트릭스 스토리지: 이력 관리가 포함된 YAML 기반 추적 매트릭스 ```bash itda-trace extract # 트레이서빌리티 ID 추출 itda-trace gaps # 갭 탐지 itda-trace matrix # 매트릭스 리포트 생성 ``` #### 엔터프라이즈 기능 | 기능 | 설명 | | ---------------- | ------------------------- | | **에러 복구** | 복구 절차를 포함한 자동 에러 분석 | | **롤백 매니저** | 파일 / 커밋 / 단계 / 스프린트 단위 롤백 | | **CI 리포터** | GitHub Actions 통합 | | **Phase -1 게이트** | 모든 단계 이전의 헌법 준수 체크 | | **스티어링 동기화** | 버전 변경 시 스티어링 파일 자동 업데이트 | #### 전체 7개 에이전트 플랫폼 업데이트 모든 프롬프트 및 템플릿을 **정확한 저장 경로**로 업데이트했습니다. - Claude Code - GitHub Copilot - Cursor - Gemini CLI - Codex CLI - Qwen Code - Windsurf #### 테스트 결과 - **단위 테스트**: 4,827건 통과 ✅ - **통합 테스트**: 660건 통과 ✅ --- ## 📊 v5.9.0의 신규 기능 ### Phase 1-4 엔터프라이즈 기능 대규모 프로젝트 및 모노레포 대응을 위한 엔터프라이즈 기능을 대폭 추가. #### 워크플로 유연성(Phase 1) - **3가지 워크플로 모드**: `small`(버그 수정), `medium`(기능 추가), `large`(설계 변경) - **자동 감지**: 피처명 패턴을 기반으로 모드를 자동 선택 - **`itda-release`**: CHANGELOG 자동 생성이 포함된 릴리스 CLI ```bash # 커밋에서 CHANGELOG 생성 itda-release # 피처의 모드 감지 itda-workflow mode --detect "feat: 사용자 인증" ``` #### 모노레포 대응(Phase 2) - **패키지 레지스트리**: `steering/packages.yml`로 의존관계 관리 - **의존관계 그래프**: Mermaid 다이어그램 생성으로 시각화 - **커버리지 추적**: 패키지별 테스트 커버리지 리포트 #### 헌법 레벨 관리(Phase 3) - **3가지 적용 레벨**: `critical`(차단), `advisory`(경고), `flexible`(제안) - **레벨별 검증**: 조항 중요도에 따라 다른 방식으로 적용 - **프로젝트별 오버라이드**: 프로젝트 유형별 커스텀 레벨 | 레벨 | 조항 | 동작 | | -------- | ----------------------------- | -------- | | Critical | CONST-001, 002, 003, 005, 009 | 워크플로를 차단 | | Advisory | CONST-004, 006, 007 | 경고만 표시 | | Flexible | CONST-008 | 제안으로 표시 | #### 프로젝트 설정(Phase 4) - **`itda-config`**: 설정 관리용 신규 CLI - **스키마 검증**: AJV로 v2.0 스키마 검증 - **자동 마이그레이션**: v1.0 설정을 v2.0으로 자동 업그레이드 ```bash itda-config validate # project.yml 검증 itda-config migrate # v2.0으로 마이그레이션 itda-config show # 유효한 설정 표시 ``` #### 오케스트레이터 통합 프로그램 접근을 위한 5개의 내장 스킬: | 스킬 | 카테고리 | 용도 | | ---------------------------- | ------------- | ------------ | | `release-manager` | release | CHANGELOG 생성 | | `workflow-mode-manager` | workflow | 모드 감지·관리 | | `package-manager` | configuration | 패키지·의존관계 분석 | | `constitution-level-manager` | validation | 레벨별 검증 | | `project-config-manager` | configuration | 설정 검증·마이그레이션 | ```javascript const { workflowModeSkill } = require('itda-sdd/src/orchestration'); const result = await workflowModeSkill.execute({ action: 'detect', featureName: 'fix: 경미한 버그' }); console.log(result.detectedMode); // 'small' ``` --- ## 📊 v5.6.0의 신규 기능 ### 엔터프라이즈 스케일 분석 & Rust 마이그레이션 지원 GCC 코드베이스(1,000만 라인 이상, 10만 파일 이상) 분석을 기반으로 한 대폭 개선. #### Large Project Analyzer - **스케일 인지 분석**: 프로젝트 크기를 자동 감지하고 적절한 전략을 선택 - **메모리 효율 처리**: 10만 파일 이상에서도 청크 기반 처리와 가비지 컬렉션 적용 - **다국어 지원**: JavaScript, TypeScript, C, C++, Python, Rust, Go, Java - **거대 함수 탐지**: 100줄+(경고), 500줄+(위험), 1000줄+(극단)의 함수를 플래그 #### CodeGraph MCP통합 - **심층 코드 그래프 분석**: CodeGraph MCP 통합으로 관계성 분석 - **콜 그래프 생성**: 설정 가능한 깊이로 호출자·피호출자 추적 - **영향 분석**: 코드 변경 시 영향 파일 식별 - **핫스팟 식별**: 고연결성 엔티티(리팩터링 후보) 탐지 #### 확장 복잡도 분석기 - **순환 복잡도**: 표준적인 결정 지점 카운트 - **인지 복잡도**: SonarSource 방식의 가독성 측정 - **심각도 레벨**: 이상적 → 경고 → 위험 → 극단의 임계값 #### Rust 마이그레이션 생성기 - **위험 패턴 탐지**: C/C++ 메모리 안전 비보장 패턴을 식별 - **마이그레이션 우선순위 스코어링**: Rust 이전 우선순위를 자동 산정 - **보안 컴포넌트 분석**: 보안 중요 코드 섹션을 플래그 ```javascript // 엔터프라이즈 스케일 프로젝트 분석(100,000파일 이상) const { LargeProjectAnalyzer, ComplexityAnalyzer } = require('itda-sdd'); const analyzer = new LargeProjectAnalyzer('/path/to/gcc'); const result = await analyzer.analyze(); console.log(result.stats); // { totalFiles: 109073, ... } // 코드 복잡도 계산 const complexity = new ComplexityAnalyzer(); const score = complexity.calculateCyclomaticComplexity(code, 'javascript'); ``` ### 이전 버전(v5.5.0) - 🔗 **GitHub 참조 기능** - 성공적인 리포지토리에서 패턴과 프랙티스를 참조 - 📦 **다중 리포지토리 대응** - `-r` / `--reference` 옵션으로 여러 개 지정 가능 - 🔍 **패턴 탐지** - Clean Architecture, Hexagonal, DDD, Monorepo 등을 자동 감지 - 🛠️ **기술 탐지** - React, Vue, Next.js, TypeScript, Rust 등을 분석 - 📈 **개선 제안** - 참조 리포지토리에서 개선 포인트를 자동 생성 - 💾 **결과 저장** - `steering/references/github-references-YYYY-MM-DD.md`에 저장 ```bash # 단일 리포지토리 참조 itda init --reference facebook/react # 다중 리포지토리 참조(축약 형식) itda init -r vercel/next.js -r facebook/react -r denoland/deno # URL 형식 itda init --reference https://github.com/tokio-rs/tokio # 브랜치 지정 itda init -r owner/repo@develop ``` ## 특징 - 🤖 **멀티 에이전트 대응**: 7개의 AI 코딩 에이전트 지원(Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Qwen Code, Windsurf) - 🔌 **MCP 서버 통합**: 고도화된 코드 분석을 위한 CodeGraphMCPServer(v2.0.0에서 추가) - 📄 **유연한 커맨드 형식**: Markdown, TOML, AGENTS.md 형식 지원 - 🎯 **27개의 전문 스킬(전 플랫폼 대응)**: 25개 플랫폼 에이전트 + 5개 오케스트레이터 내장 스킬(v5.9.0) - **Claude Code**: Skills API(25개 스킬 + 5개 내장) - **GitHub Copilot & Cursor**: AGENTS.md(공식 지원) - **기타 4개 에이전트**: AGENTS.md(호환 형식) - 📋 **헌법 거버넌스**: 9개의 불변 조항 + Phase-1 게이트로 품질 보증 - 📝 **EARS 요구사항 생성기**: 5가지 EARS 패턴으로 명확한 요구사항 작성(v0.8.0) - 🏗️ **설계 문서 생성기**: 추적성 포함 C4 모델과 ADR 생성(v0.8.2) - 🔄 **변경 관리 시스템**: 브라운필드 프로젝트용 차분 사양(v0.8.6) - 🔍 **갭 탐지 시스템**: 고립된 요구사항 및 테스트되지 않은 코드를 식별(v0.8.7) - 🧭 **자동 갱신 프로젝트 메모리**: 스티어링 시스템이 아키텍처, 기술 스택, 제품 컨텍스트를 유지 - 🚀 **자동 온보딩**: itda-onboard가 기존 프로젝트를 분석하고 스티어링 문서를 생성(2~5분) - 🔄 **자동 동기화**: itda-sync가 코드베이스 변경을 감지해 스티어링 문서를 최신 상태로 유지 - 🔍 **지능형 코드 분석**: itda-analyze가 품질 메트릭, 복잡도 분석, 기술 부채 탐지를 제공 - 🤝 **팀 협업**: itda-share가 메모리 공유, 임포트/익스포트, 멀티 플랫폼 동기화를 제공(v0.6.0) - ✅ **헌법 검증(Validation)**: itda-validate가 9개의 불변 거버넌스 조항과 Phase-1 게이트를 강제(v0.7.0) - ✅ **완전한 추적성**: 요구사항 → 설계 → 코드 → 테스트 매핑 - 🌐 **이중언어 문서**: 모든 에이전트 생성 문서는 영어와 한국어로 모두 생성 ## 지원 AI 코딩 에이전트 ITDA는 7개의 AI 코딩 에이전트를 지원하며, 각 에이전트에 최적화된 설정을 제공합니다. | 에이전트 | 스킬 API | 27 스킬 | 커맨드 형식 | 커맨드 파일 형식 | 설치 디렉터리 | | ------------------ | --------- | ------------- | ---------------- | -------------------- | --------------------------------------------- | | **Claude Code** | ✅ (27 스킬) | ✅ | `/sdd-*` | Markdown | `.claude/skills/`, `.claude/commands/` | | **GitHub Copilot** | ❌ | ✅ (AGENTS.md) | `#sdd-*` | Markdown + AGENTS.md | `.github/prompts/`, `.github/AGENTS.md` | | **Cursor IDE** | ❌ | ✅ (AGENTS.md) | `/sdd-*` | Markdown + AGENTS.md | `.cursor/commands/`, `.cursor/AGENTS.md` | | **Gemini CLI** | ❌ | ✅ (GEMINI.md) | `/sdd-*` | TOML + GEMINI.md | `.gemini/commands/`, `GEMINI.md` | | **Codex CLI** | ❌ | ✅ (AGENTS.md) | `/prompts:sdd-*` | Markdown + AGENTS.md | `.codex/prompts/`, `.codex/AGENTS.md` | | **Qwen Code** | ❌ | ✅ (AGENTS.md) | `/sdd-*` | Markdown + AGENTS.md | `.qwen/commands/`, `.qwen/AGENTS.md` | | **Windsurf IDE** | ❌ | ✅ (AGENTS.md) | `/sdd-*` | Markdown + AGENTS.md | `.windsurf/workflows/`, `.windsurf/AGENTS.md` | **주의사항**： - 스킬 API는 Claude Code 전용입니다 - 전 7개 플랫폼이 27개 스킬을 지원합니다(Skills API 또는 AGENTS.md 경유) - v5.9.0에서 5개의 내장 오케스트레이터 스킬을 추가(release, workflow, package, constitution-level, project-config) - AGENTS.md: OpenAI 사양이며 GitHub Copilot & Cursor가 공식 지원 - Gemini CLI는 TOML 형식 + GEMINI.md 통합을 사용 - 기타 에이전트는 Markdown 형식 + AGENTS.md를 사용 --- ## 헌법 거버넌스 ITDA는 품질 보증을 위해 9개의 헌법 조항을 강제합니다: ```bash # 헌법 준수 여부 검증 itda-validate all itda-validate constitution itda-validate gates itda-validate complexity ``` **9개 조항**: 1. **라이브러리 퍼스트(Library-First) 원칙** - 모든 기능은 독립된 라이브러리로 시작한다 2. **CLI 인터페이스 의무** - 모든 라이브러리는 CLI 기능을 공개해야 한다 3. **테스트 퍼스트(Test-First) 요구** - 코드보다 먼저 테스트를 작성한다(커버리지 80% 필수) 4. **EARS 요구사항 포맷** - 모호함 없는 요구사항을 위한 5가지 EARS 패턴 5. **추적성(트레이서빌리티) 의무** - 100% 추적성: 요구사항 ↔ 설계 ↔ 코드 ↔ 테스트 6. **프로젝트 메모리** - Steering 시스템이 프로젝트 컨텍스트를 유지한다 7. **단순성 게이트(Simplicity Gate)** - 초기에는 최대 3개 서브프로젝트(Phase-1 게이트) 8. **추상화 방지 게이트** - 프레임워크 API를 직접 사용한다(Phase-1 게이트) 9. **통합 퍼스트 테스트(Integration-First Test)** - 통합 테스트는 실서비스를 사용한다(목(Mocking) 금지) **Phase-1 게이트**: 조항 VII & VIII의 구현 전 검증 체크포인트. 상세: - [steering/rules/constitution.md](steering/rules/constitution.md) - 전체 헌법 텍스트 - [steering/rules/phase-gates.md](steering/rules/phase-gates.md) - 승인 프로세스 및 활성 게이트 ## 퀵스타트 ### npx로 설치 ```bash # 선호하는 에이전트용으로 ITDA 초기화 # Claude Code(기본값) - 25 Skills API npx itda-sdd init npx itda-sdd init --claude # GitHub Copilot - 25 에이전트(AGENTS.md, 공식 지원) npx itda-sdd init --copilot # Cursor IDE - 25 에이전트(AGENTS.md, 공식 지원) npx itda-sdd init --cursor # Gemini CLI - 25 에이전트(GEMINI.md 통합) npx itda-sdd init --gemini # Codex CLI - 25 에이전트(AGENTS.md) npx itda-sdd init --codex # Qwen Code - 25 에이전트(AGENTS.md) npx itda-sdd init --qwen # Windsurf IDE - 25 에이전트(AGENTS.md) npx itda-sdd init --windsurf # 또는 전역 설치 npm install -g itda-sdd itda init --claude # 또는 --copilot, --cursor 등 # 기존 프로젝트 온보딩(자동 분석) itda-onboard # 코드베이스와 스티어링 문서 동기화 itda-sync itda-sync --dry-run # 변경 사항 미리보기 itda-sync --auto-approve # 자동 적용(CI/CD) # 코드 품질 분석(v0.5.0) itda-analyze # 전체 분석 itda-analyze --type=quality # 품질 메트릭만 itda-analyze --type=dependencies # 의존관계만 itda-analyze --type=security # 보안 감사 itda-analyze --output=report.md # 리포트 저장 # 팀과 프로젝트 메모리 공유(v0.6.0) itda-share export # 메모리를 JSON으로 내보내기 itda-share import memories.json # 팀원에게서 가져오기 itda-share sync --platform=copilot # 특정 플랫폼으로 동기화 # 헌법 준수 검증(v0.7.0) itda-validate constitution # 전체 9개 조항 검증 itda-validate article 3 # 테스트 퍼스트 원칙 검증 itda-validate gates # Phase-1 게이트 검증 itda-validate complexity # 복잡도 제한 체크 itda-validate all -v # 상세 포함 전체 검증 # EARS 요구사항 문서 생성(v0.8.0) itda-requirements init "사용자 인증" # 요구사항 문서 초기화 itda-requirements add # 인터랙티브로 요구사항 추가 itda-requirements list # 전체 요구사항 목록 표시 itda-requirements validate # EARS 형식 검증 itda-requirements trace # 추적성 매트릭스 표시 # 설계 문서 생성(v0.8.2) itda-design init "사용자 인증" # 설계 문서 초기화 itda-design add-c4 context # C4 컨텍스트 다이어그램 추가 itda-design add-c4 container --format plantuml # PlantUML로 컨테이너 다이어그램 추가 itda-design add-adr "JWT 토큰 사용" # 아키텍처 결정 기록(ADR) 추가 itda-design validate # 설계 완전성 검증 itda-design trace # 요구사항 추적성 표시 # 설계를 태스크로 분해(v0.8.4) itda-tasks init "사용자 인증" # 태스크 분해 초기화 itda-tasks add "데이터베이스 스키마" # 인터랙티브로 태스크 추가 itda-tasks list # 전체 태스크 목록 표시 itda-tasks list --priority P0 # 중요 태스크만 표시 itda-tasks update 001 "In Progress" # 태스크 상태 업데이트 itda-tasks validate # 태스크 완전성 검증 itda-tasks graph # 의존관계 그래프 표시 # 엔드투엔드 추적성(v0.8.5) itda-trace matrix # 추적성 매트릭스 생성 itda-trace matrix --format markdown > trace.md # Markdown으로 내보내기 itda-trace coverage # 커버리지 통계 계산 itda-trace coverage --min-coverage 100 # 100% 커버리지 요구 itda-trace gaps # 고립된 요구사항/코드 탐지 itda-trace requirement REQ-AUTH-001 # 특정 요구사항 추적 itda-trace validate # 100% 추적성 검증(제5조) itda-trace bidirectional # 양방향 추적성 분석(v0.9.4) itda-trace impact REQ-AUTH-001 # 요구사항 변경 영향 분석(v0.9.4) itda-trace statistics # 포괄적 프로젝트 통계(v0.9.4) # 브라운필드 프로젝트용 변경 관리(v0.8.6) itda-change init CHANGE-001 --title "인증 기능 추가" # 변경 제안 생성 itda-change validate CHANGE-001 --verbose # 차분 사양 검증 itda-change apply CHANGE-001 --dry-run # 변경 미리보기 itda-change apply CHANGE-001 # 코드베이스에 변경 적용 itda-change archive CHANGE-001 # specs/에 아카이브 itda-change list --status pending # 보류 중 변경 목록 itda-change list --format json # JSON 형식으로 목록 # 갭 탐지와 커버리지 검증(v0.8.7) itda-gaps detect # 전체 갭 탐지 itda-gaps detect --verbose # 상세 갭 정보 표시 itda-gaps requirements # 고립된 요구사항 탐지 itda-gaps code # 테스트되지 않은 코드 탐지 itda-gaps coverage # 커버리지 통계 계산 itda-gaps coverage --min-coverage 100 # 100% 커버리지 요구 itda-gaps detect --format markdown > gaps.md # 갭 리포트 내보내기 ``` ### 프로젝트 타입 초기화 시 ITDA는 **프로젝트 타입 선택**을 요구합니다. 이 선택에 따라 사용 가능한 워크플로와 기능이 결정됩니다. #### Greenfield（0→1） - **개요**: 완전히 새로운 프로젝트를 제로에서 시작 - **사용 예**: - 신규 애플리케이션 개발 - 개념 증명(PoC) 프로젝트 - 그린필드 마이크로서비스 - **활성화되는 기능**: - 전체 8단계 SDD 워크플로(조사 → 모니터링) - `/sdd-steering` - 초기 프로젝트 메모리 생성 - `/sdd-requirements` - 제로에서 신규 요구사항 작성 - `/sdd-design` - 아키텍처 설계(C4 모델 + ADR) - `/sdd-tasks` - 요구사항을 태스크로 분해 - `/sdd-implement` - 기능 구현(테스트 퍼스트) - `/sdd-validate` - 헌법 준수 여부 검증 - **장점**: - 베스트 프랙티스가 처음부터 적용된 클린한 출발 - 프로젝트 첫날부터 헌법 거버넌스 적용 - 요구사항부터 코드까지 완전한 추적성 확보 #### Brownfield（1→n） - **개요**: 기존 코드베이스를 기반으로 작업 - **사용 예**: - 기존 애플리케이션에 기능 추가 - 레거시 코드 리팩터링 - 시스템 이전/모더나이제이션 - **활성화되는 기능**: - 차분 사양(ADDED / MODIFIED / REMOVED) - `/sdd-change-init` - 변경 제안 생성 - `/sdd-change-apply` - 영향 분석 포함 변경 적용 - `/sdd-change-archive` - 완료된 변경 아카이브 - `change-impact-analyzer`스킬(Claude Code) - 자동 영향 분석 - 리버스 엔지니어링: `/sdd-steering`이 기존 코드 분석 - **장점**: - 영향 분석을 통한 안전한 점진적 변경 - 기존 아키텍처를 유지하며 단계적 개선 가능 - 변경 내용과 변경 사유에 대한 완전한 감사 추적 기록 #### Both (혼합) - **개요**: 복잡한 시나리오를 위한 하이브리드 접근 방식 - **사용 예**: - 모놀리스 → 마이크로서비스 이전(브라운필드 + 그린필드 서비스) - 플랫폼 모더나이제이션(일부 유지, 일부 재구축) - 성숙도가 다른 멀티 컴포넌트 시스템 - **활성화되는 기능**: - Greenfield + Brownfield의 모든 기능 - 컴포넌트별 워크플로 선택 가능 - 하나의 프로젝트 내에서 차분 사양과 그린필드 사양 혼용 - **장점**: - 복잡한 전환 프로젝트에 대한 최대한의 유연성 - 모든 컴포넌트에 대해 일관된 스티어링/거버넌스 제공 - 전체 모더나이제이션을 단일 도구로 수행 가능 **선택 예시**: ```text ? Project type: ❯ Greenfield (0→1) ← 신규 프로젝트 Brownfield (1→n) ← 기존 코드베이스 Both ← 복잡 / 하이브리드 시나리오 ``` ## 문서 포괄적인 가이드는 `docs/guides/`에서 확인할 수 있습니다: - **[브라운필드 튜토리얼](docs/guides/brownfield-tutorial.md)** - 기존 프로젝트에서의 변경 관리 단계별 가이드 - **[차분 사양 가이드](docs/guides/delta-spec-guide.md)** - 변경 추적 포맷 레퍼런스 - **[변경 관리 워크플로](docs/guides/change-management-workflow.md)** - 엔드투엔드 워크플로 문서 - **[추적성 매트릭스 가이드](docs/guides/traceability-matrix-guide.md)** - 추적성 시스템 사용 방법 - **[비디오 튜토리얼 기획](docs/guides/video-tutorial-plan.md)** - 비디오 콘텐츠 스크립트 ### 설치되는 구성 요소 #### Claude Code（Skills API） ```text your-project/ ├── .claude/ │ ├── skills/ # 25개 Skills API (Claude Code 전용) │ │ ├── orchestrator/ │ │ ├── steering/ │ │ ├── requirements-analyst/ │ │ └── ... (총 22개 이상) │ ├── commands/ # 슬래시 커맨드(/sdd-*) │ └── CLAUDE.md # Claude Code 가이드 ├── steering/ # 프로젝트 메모리(전 에이전트 공통) │ ├── structure.md # 아키텍처 패턴 │ ├── tech.md # 기술 스택 │ ├── product.md # 제품 컨텍스트 │ └── rules/ │ ├── constitution.md # 9개 헌법 조항 │ ├── workflow.md # 8단계 SDD 워크플로 │ └── ears-format.md # EARS 문법 가이드 ├── templates/ # 문서 템플릿(전 에이전트 공통) └── storage/ # 사양, 변경, 기능(전 에이전트 공통) ``` #### 기타 에이전트 (GitHub Copilot, Cursor, Gemini 등) ```text your-project/ ├── .github/prompts/ # GitHub Copilot용(#sdd-* / Markdown) │ ├── AGENTS.md # 25개 에이전트 정의(공식 지원) │ 또는 ├── .cursor/commands/ # Cursor용(/sdd-* / Markdown) │ ├── AGENTS.md # 25개 에이전트 정의(공식 지원) │ 또는 ├── .gemini/commands/ # Gemini CLI용(/sdd-* / TOML) │ │ ├── sdd-steering.toml │ │ ├── sdd-requirements.toml │ │ └── ... (총 6개 TOML 파일) │ 또는 ├── .codex/prompts/ # Codex CLI용(/prompts:sdd-* / Markdown) │ ├── AGENTS.md # 25개 에이전트 정의 │ 또는 ├── .qwen/commands/ # Qwen Code용(/sdd-* / Markdown) │ ├── AGENTS.md # 25개 에이전트 정의 │ 또는 ├── .windsurf/workflows/ # Windsurf용(/sdd-* / Markdown) │ ├── AGENTS.md # 25개 에이전트 정의 │ ├── GEMINI.md (루트, Gemini용) # 기존 파일에 25개 에이전트 통합 ├── steering/ # 프로젝트 메모리(공통) ├── templates/ # 문서 템플릿(공통) └── storage/ # 사양, 변경, 기능(공통) ``` **주요 차이점**： - **Claude Code**: 25개 Skills API(전용) + Markdown 커맨드 - **GitHub Copilot & Cursor**: AGENTS.md(공식 지원) + Markdown 커맨드 - **Gemini CLI**: GEMINI.md 통합(25개 에이전트) + TOML 커맨드(고유) - **その他**: AGENTS.md(호환) + Markdown 커맨드 - **전 플랫폼 공통**: 동일한 25개 에이전트, 구현 방식만 상이 ## 사용 방법 ### CLI 커맨드 ITDA는 프로젝트 관리를 위한 다양한 CLI 커맨드를 제공합니다. ```bash # 버전 확인 itda --version itda -v # 도움말 itda --help # 종합 정보 출력 itda info # 프로젝트 상태 확인 itda status # 헌법 준수 검증 itda validate itda validate --verbose # 상세 출력 itda validate --all # 전체 기능 검증 # ITDA 초기화(대화형) itda init ``` #### itda status ITDA 프로젝트의 현재 상태를 표시합니다. ```text 📊 ITDA Project Status ✅ ITDA is initialized 📁 Claude Code Skills: 25 installed Location: .claude/skills/ 🧭 Steering Context: ✅ structure.md (updated: 2025-11-16) ✅ tech.md (updated: 2025-11-16) ✅ product.md (updated: 2025-11-16) ✅ Constitutional Governance: Enabled 📄 Specifications: 3 documents Latest specs: - auth-requirements.md - auth-design.md - auth-tasks.md 💡 Next steps: - Review steering files in steering/ - Create requirements: /sdd-requirements [feature] - Validate compliance: itda validate ``` #### itda validate 헌법 준수에 대한 간이 검증을 실행합니다. - **조항 I**: 라이브러리 퍼스트 원칙(`lib/` 디렉터리 확인) - **조항 II**: CLI 인터페이스 의무(`cli.ts` 파일 확인) - **조항 IV**: EARS 요구사항 형식(EARS 패턴 검증) - **조항 VI**: 프로젝트 메모리(스티어링 파일 확인) 보다 포괄적인 검증을 위해서는 에이전트의 `/sdd-validate`(또는 이에 상응하는) 커맨드를 사용하십시오. ### 에이전트별 전용 커맨드 #### Claude Code ```bash # 프로젝트 메모리 생성 /sdd-steering # 요구사항 작성 /sdd-requirements authentication # 아키텍처 설계 /sdd-design authentication # 태스크 분해 /sdd-tasks authentication # 기능 구현 /sdd-implement authentication # 헌법 준수 검증 /sdd-validate authentication ``` **스킬(자동 실행)**: Claude Code는 요청에 따라 적절한 스킬을 자동으로 선택합니다. - “코드를 리뷰해 줘” → `code-reviewer` 스킬 - “사용자 로그인 요구사항을 작성해 줘” → `requirements-analyst` 스킬 - “결제용 API를 설계해 줘” → `api-designer` 스킬 #### GitHub Copilot ```bash # 커스텀 프롬프트에는 # 프리픽스를 사용 #sdd-steering #sdd-requirements authentication #sdd-design authentication #sdd-tasks authentication #sdd-implement authentication #sdd-validate authentication ``` #### Gemini CLI ```bash # 커맨드에는 / 프리픽스를 사용 (TOML 형식) /sdd-steering /sdd-requirements authentication /sdd-design authentication /sdd-tasks authentication /sdd-implement authentication /sdd-validate authentication ``` **주의**: Gemini CLI의 커맨드는 Markdown이 아니라 **TOML 형식(`.toml` 파일)**으로 정의됩니다. #### Cursor IDE、Qwen Code、Windsurf ```bash # 커맨드에는 / 프리픽스를 사용 (Markdown 형식) /sdd-steering /sdd-requirements authentication /sdd-design authentication /sdd-tasks authentication /sdd-implement authentication /sdd-validate authentication ``` #### Codex CLI ```bash # /prompts: 프리픽스를 사용 /prompts:sdd-steering /prompts:sdd-requirements authentication /prompts:sdd-design authentication /prompts:sdd-tasks authentication /prompts:sdd-implement authentication /prompts:sdd-validate authentication ``` ## 25개 에이전트 개요 (전 플랫폼 공통 지원) **총 7개 플랫폼에서 사용 가능**： - **Claude Code**: Skills API(자동 실행) - **GitHub Copilot & Cursor**: AGENTS.md (공식 지원, `@에이전트명`으로 참조) - **Gemini、Windsurf、Codex、Qwen**: AGENTS.md (호환 형식, 자연어로 참조) ### 오케스트레이션 및 관리 (3) - **orchestrator** - 멀티 스킬 워크플로의 마스터 코디네이터 - **steering** - 프로젝트 메모리 매니저(컨텍스트 자동 갱신) - **constitution-enforcer** - 거버넌스 검증(9개 조항 + Phase-1 게이트) ### 요구사항 및 계획 (3) - **requirements-analyst** - EARS 형식 요구사항 생성 - **project-manager** - 프로젝트 계획, 일정 수립, 리스크 관리 - **change-impact-analyzer** - 브라운필드 변경 영향 분석 ### 아키텍처 및 설계 (4) - **system-architect** - C4 모델 + ADR 기반 아키텍처 설계 - **api-designer** - REST / GraphQL / gRPC API 설계 - **database-schema-designer** - 데이터베이스 설계, ER 다이어그램, DDL - **ui-ux-designer** - UI/UX 설계, 와이어프레임, 프로토타입 ### 개발 (1) - **software-developer** - 다중 언어 코드 구현 ### 품질 및 리뷰 (5) - **test-engineer** - EARS 매핑 기반 단위 / 통합 / E2E 테스트 - **code-reviewer** - 코드 리뷰, SOLID 원칙 적용 - **bug-hunter** - 버그 조사 및 근본 원인 분석 - **quality-assurance** - QA 전략 및 테스트 계획 - **traceability-auditor** - 요구사항 ↔ 코드 ↔ 테스트 커버리지 검증 ### 보안 및 성능 (2) - **security-auditor** - OWASP Top 10 기반 취약점 탐지 - **performance-optimizer** - 성능 분석 및 최적화 ### 인프라 및 운영 (5) - **devops-engineer** - CI/CD 파이프라인, Docker / Kubernetes - **cloud-architect** - AWS/Azure/GCP、IaC（Terraform/Bicep） - **database-administrator** - 데이터베이스 운영 및 튜닝 - **site-reliability-engineer** - 프로덕션 모니터링, SLO/SLI, 인시던트 대응 - **release-coordinator** - 멀티 컴포넌트 릴리스 관리 ### 문서화 및 전문 영역 (2) - **technical-writer** - 기술 문서, API 문서 작성 - **ai-ml-engineer** - ML 모델 개발 및 MLOps ## 9조 헌법 거버넌스 ITDA는 변경 불가능한 9개의 헌법 조항을 시행합니다. 1. **라이브러리 퍼스트 원칙** - 모든 기능은 라이브러리로 시작한다 2. **CLI 인터페이스 의무** - 모든 라이브러리는 CLI를 제공해야 한다 3. **테스트 퍼스트 명령** - 코드 이전에 테스트를 작성한다(레드·그린·블루) 4. **EARS 요구사항 형식** - 명확하고 모호하지 않은 요구사항 5. **추적성 의무** - 100% 커버리지 필수 6. **프로젝트 메모리** - 모든 스킬은 작업 전 스티어링을 우선 확인한다 7. **단순성 게이트(Simplicity Gate)** - 초기에는 최대 3개 프로젝트 8. **안티 추상화 게이트(Anti-Abstraction Gate)** - 프레임워크 기능을 직접 사용 9. **통합 퍼스트 테스트(Integration-First Testing)** - 목(mock)보다 실서비스 우선 ## SDD 워크플로 (8단계) ```text 1. 조사 → 2. 요구사항 → 3. 설계 → 4. 태스크 → 5. 구현 → 6. 테스트 → 7. 배포 → 8. 모니터링 ``` 각 단계에는 다음이 포함됩니다. - 전용 스킬 - 품질 게이트 - 추적성 요구사항 - 헌법 검증 ## EARS 요구사항 형식 ```markdown ### 요구사항: 사용자 로그인 WHEN 사용자가 유효한 인증 정보를 제공할 경우, THEN 시스템 SHALL 사용자를 인증한다 AND 시스템 SHALL 세션을 생성한다. #### 시나리오: 로그인 성공 - WHEN 사용자가 올바른 이메일 주소와 비밀번호를 입력한다 - THEN 시스템 SHALL 인증 정보를 검증한다 - AND 시스템 SHALL 대시보드로 리다이렉트한다 ``` ## 이중언어 문서 **모든 에이전트가 생성하는 문서는 영어와 한국어 두 가지 언어로 생성됩니다.** ### 언어 정책 - **영어**: 참조 / 소스 문서(`.md`) - **한국어**: 번역본(.ko.md) - **스킬 실행 시**: 항상 영어 버전을 기준으로 작업 - **코드 참조**: 요구사항 ID, 기술 용어는 영어 그대로 유지 ### 이중언어로 생성되는 파일 **스티어링 컨텍스트**： - `steering/structure.md` + `steering/structure.ko.md` - `steering/tech.md` + `steering/tech.ko.md` - `steering/product.md` + `steering/product.ko.md` **사양 문서**： - `storage/specs/auth-requirements.md` + `storage/specs/auth-requirements.ko.md` - `storage/specs/auth-design.md` + `storage/specs/auth-design.ko.md` - `storage/specs/auth-tasks.md` + `storage/specs/auth-tasks.ko.md` ### 생성 순서 1. **영어 버전을 먼저 생성** (참조/소스) 2. **한국어 버전을 이후 생성** (번역) 3. 기술 용어(REQ-XXX-NNN, EARS 키워드, API 엔드포인트)는 영어 유지 4. 두 버전을 항상 동기화하여 유지 ## 차분 사양(브라운필드) ```markdown ## 추가된 요구사항 ### REQ-NEW-001: 이중 인증(2FA) ... ## 변경된 요구사항 ### REQ-001: 사용자 인증 **이전**: 이메일 + 비밀번호 **변경 후**: 이메일 + 비밀번호 + OTP ... ## 삭제된 요구사항 ### REQ-OLD-005: 로그인 상태 유지 **사유**: 보안 정책 변경 ``` ## 사용 예시 ### 그린필드 프로젝트 (0→1) ```bash # 1. 초기화 npx itda-sdd init # 2. 스티어링 생성 /sdd-steering # 3. 요구사항 작성 /sdd-requirements user-authentication # 4. 아키텍처 설계 /sdd-design user-authentication # 5. 태스크로 분해 /sdd-tasks user-authentication # 6. 구현 /sdd-implement user-authentication ``` ### 브라운필드 프로젝트 (1→n) ```bash # 1. 기존 코드베이스에서 초기화 npx itda-sdd init # 2. 기존 코드로부터 스티어링 생성 /sdd-steering # 3. 변경 제안 생성 /sdd-change-init add-2fa # 4. 영향 분석 (change-impact-analyzer 스킬을 통해 자동 수행) # 5. 변경 구현 /sdd-change-apply add-2fa # 6. 변경 아카이브 /sdd-change-archive add-2fa ``` ## 설정 ### MCP 서버 통합 ITDA v2.0.0은 고급 코드 분석을 위해 CodeGraphMCPServer와 통합됩니다. #### 옵션 1: Claude Code (터미널) ```bash # CodeGraph MCP를 pipx로 설치 (--force로 항상 최신 버전 유지) pipx install --force codegraph-mcp-server # Claude Code에 추가 claude mcp add codegraph -- codegraph-mcp serve --repo . # 설치 확인 claude mcp list ``` #### 옵션 2: VS Code + Claude 확장 1. **사전 조건 설치**: ```bash # --force로 기존 설치도 최신 버전으로 갱신 pipx install --force codegraph-mcp-server ``` 2. **VS Code 설정** (`.vscode/mcp.json`): ```json { "servers": { "codegraph": { "type": "stdio", "command": "codegraph-mcp", "args": ["serve", "--repo", "${workspaceFolder}"] } } } ``` 3. **또는 Claude Desktop 설정 사용** (`~/.claude/claude_desktop_config.json` macOS/Linux、`%APPDATA%\Claude\claude_desktop_config.json` Windows): ```json { "mcpServers": { "codegraph": { "command": "codegraph-mcp", "args": ["serve", "--repo", "/path/to/your/project"] } } } ``` #### 옵션 3: npx (설치 불필요) ```bash # npx를 통해 추가 (글로벌 설치 불필요) claude mcp add codegraph -- npx -y @anthropic/codegraph-mcp --codebase . ``` #### MCP 서버 동작 확인 설정 완료 후 Claude에서 테스트: ```text init_graph 도구를 사용하여 이 코드베이스를 분석해 주세요 ``` 정상 동작 시 코드 그래프 초기화 결과가 출력됩니다. **사용 가능한 MCP 도구 (총 14개)**: | 카테고리 | 도구 | 설명 | | ------ | --------------------------------------------------------------------- | ------------------ | | 코드 그래프 | `init_graph`, `get_code_snippet`, `find_callers`, `find_dependencies` | 코드 그래프 생성 및 쿼리 | | 검색 | `local_search`, `global_search`, `query_codebase` | GraphRAG 기반 시맨틱 검색 | | 분석 | `analyze_module_structure`, `suggest_refactoring` | 코드 구조 분석 | | 내비게이션 | `jump_to_definition`, `find_implementations` | 코드 탐색 | **에이전트 × MCP 도구 매핑**: | 에이전트 | 주요 MCP 도구 | 용도 | | ----------------------- | ------------------------------------------- | --------- | | @change-impact-analyzer | `find_dependencies`, `find_callers` | 영향 분석 | | @traceability-auditor | `query_codebase`, `find_callers` | 추적성 검증 | | @system-architect | `analyze_module_structure`, `global_search` | 아키텍처 분석 | | @code-reviewer | `suggest_refactoring`, `get_code_snippet` | 코드 품질 리뷰 | | @security-auditor | `find_callers`, `query_codebase` | 보안 취약점 탐지 | 기타 MCP 서버 연동： - **Context7 MCP** - 최신 라이브러리 문서(Next.js, React 등) - **Azure MCP** - Azure 리소스 관리 - **Microsoft Learn MCP** - Microsoft 공식 문서 스킬은 필요에 따라 사용 가능한 MCP 서버를 자동으로 선택하여 사용합니다. ### 커스터마이징 프로젝트 요구에 맞게 스티어링 파일을 수정할 수 있습니다. ```bash # 아키텍처 패턴 steering/structure.md # 기술 스택 steering/tech.md # 제품 컨텍스트 steering/product.md # 헌법 규칙(필요 시) steering/rules/constitution.md ``` ## 개발 ```bash # 리포지토리 클론 git clone https://github.com/your-org/itda.git cd itda # 의존성 설치 npm install # 테스트 실행 npm test # 로컬 개발용 링크 npm link itda init ``` ## 기여 기여를 환영합니다. 자세한 내용은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고해 주세요. ## 지원 ITDA가 도움이 되었다면 아래 방법으로 지원해 주세요. - ⭐ **리포지토리에 스타 추가** - 더 많은 사람이 ITDA를 발견하는 데 도움이 됩니다 - 🐛 **이슈 보고** - 개선에 기여해 주세요 - 💡 **기능 제안** - 여러분의 아이디어를 환영합니다 - 📝 **경험 공유** - 블로그에 ITDA 사용기를 작성해 주세요 ## 라이선스 MIT 라이선스 – 자세한 내용은 [LICENSE](LICENSE)를 참고하세요. ## 크레딧 ITDA는 다음 프레임워크의 장점을 통합했습니다. - **itdda** - 20 에이전트 시스템, 스티어링, EARS 형식 - **OpenSpec** - 차분 사양, 브라운필드 지원 - **ag2**（AutoGen） - 멀티 에이전트 오케스트레이션 - **ai-dev-tasks** - 단순성, 점진적 복잡도 관리 - **k-sdd** - P 라벨 병렬화, 검증 게이트 - **spec-kit** - 헌법 거버넌스, 테스트 퍼스트 ## 📚 추가 정보 - [📖 문서](docs/) - [📋 SRS v3.0.0](docs/requirements/srs/srs-itda-v3.0.0.ko.md) - [📅 프로젝트 계획 v3.0.0](docs/plans/project-plan-v3.0.0.ko.md) - [🏗️ 블루프린트](Next-Generation-SDD-Tool-Blueprint-v3-25-Skills.md) - [📊 프로젝트계획](PROJECT-PLAN-ITDA.md) ---
**🎋 ITDA** - 잇다 - 사양, 설계, 코드를 연결한다!