AI SDLC Scaffold

Claude Code를 활용한 **AI 우선 소프트웨어 개발 (AI-first software development)**을 위한 저장소 템플릿(repository template)입니다. 전체 소프트웨어 개발 생명주기(SDLC)를 명세(Specification), 설계(Design), 코드(Code), 배포(Deploy)의 네 가지 단계로 구성하며, 각 단계는 무엇을, 언제, 어떻게 확인할지, 그리고 무엇을 해야 하는지를 인코딩한 폴더 구조, 산출물(artifacts), 그리고 에이전트 지침(agent instructions)을 포함합니다. 이를 통해 모든 프로젝트 지식은 저장소 내에 존재하며, 인간은 높은 수준에서 감독할 수 있습니다.

이것은 도구(tool), 라이브러리(library), 또는 애플리케이션(application)이 아닙니다. 이것은 **시작용 스캐폴드 (starting scaffold)**입니다. 이를 클론(clone)하거나 복사한 다음, 실제 프로젝트가 구체화됨에 따라 내용을 채워 넣으십시오.

이 스캐폴드는 네 가지 핵심 원칙을 기반으로 구축되었습니다:

1. AI 우선 개발 모델 (AI-first development model) — 인간이 감독하고, 명세를 정의하며, 방향을 설정하는 동안 AI 에이전트(AI agents)가 작업을 수행하도록 설계되었습니다.
2. 모든 것을 저장소에 (Everything-in-repo) — 명세(specification), 요구사항(requirements), 아키텍처(architecture), 결정 사항(decisions), 작업 추적(task tracking)이 모두 소스 코드와 함께 저장되어 버전 관리되며, 외부 도구 없이도 에이전트가 항상 접근할 수 있습니다.
3. 컨텍스트 윈도우 효율성 (Context-window efficiency) — 계층적 지침(hierarchical instructions), 두 개의 파일로 구성된 결정 기록(decision records), 단계별 인덱스(phase-level indexes)를 통해 에이전트가 로드해야 하는 토큰(token)의 양을 최소화합니다.
4. 억제가 아닌 결정 기록 (Decision capture, not suppression) — 에이전트는 설정된 패턴 내에서 자율적으로 결정합니다. 모든 결정은 인간의 검토와 일관성을 위해 저장소에 기록됩니다.

근거(rationale), 핵심 원칙 및 설계 선택에 대한 더 심도 있는 논의는 RATIONALE.md를 참조하십시오.

빠른 시작 (Quick Start)

옵션 A — degit 사용 (권장)

npx degit pangon/ai-sdlc-scaffold my-project
cd my-project
rm -f CONTRIBUTING.md CONTRIBUTORS.md LICENSE NOTICE RATIONALE.md README.md
...

degit은 git 히스토리를 가져오지 않고 저장소 내용만 복사하여 깨끗한 시작 지점을 제공합니다. Node.js가 필요하지만 프로젝트에 어떠한 의존성(dependency)도 설치하지 않습니다. rm 단계는 스캐폴드의 일부가 아닌 저장소 전용 파일들을 제거합니다.

옵션 B — 수동 복사 (Manual copy)

1. 이 저장소(repository)를 다운로드하거나 클론(clone)합니다.
2. 모든 파일과 디렉토리(.claude/와 같은 숨겨진 디렉토리 포함)를 새로운 프로젝트 폴더로 복사합니다.
3. 새로운 히스토리(history)로 시작하기 위해 .git/ 디렉토리를 제거합니다.
4. 저장소 전용 파일들을 제거합니다: rm -f CONTRIBUTING.md CONTRIBUTORS.md LICENSE NOTICE RATIONALE.md README.md.
5. 새로운 저장소를 초기화합니다: git init && git add -A && git commit -m "Initial scaffold".

그 다음 단계

1. Claude Code에서 /SDLC-init을 실행합니다: 초기화 스킬(initialization skill)은 CLAUDE.md에 프로젝트 설명을 설정하여 에이전트(agent)가 시작부터 올바른 컨텍스트(context)를 가질 수 있도록 합니다.
2. 내장된 skills를 사용하여 단계별로 진행합니다 (Specification → Design → Code → Deploy). 요구사항 수집부터 배포까지 각 단계를 자동화하려면 /를 입력한 후 스킬 이름을 입력하세요. 또는 커스텀 프롬프트(custom prompts)를 사용할 수도 있습니다: CLAUDE.<phase>.md 계층 구조는 에이전트가 각 단계에서 올바르게 작동하는 데 필요한 모든 컨텍스트를 제공합니다.

수동 편집은 강력히 권장하지 않습니다. 아티팩트(artifacts)와 코드에 대한 모든 변경 사항은 지침 파일(instruction files), 기존 아티팩트, 그리고 이상적으로는 스킬(skill)에 의해 동작이 제어되는 AI 에이전트를 통해 이루어져야 합니다. 이를 통해 절차가 준수되고, 결정 사항이 기록되며, 시스템의 일관성이 유지됩니다.

구조 (Structure)

├── CLAUDE.md                         # 루트 AI 지침 (여기서 시작)
├── RATIONALE.md                      # 핵심 원칙 및 설계 근거 (design rationale)
│
...

핵심 개념 (Key Concepts)

핵심 개념 (Key Concepts)

• 단계 기반 개발 (Phase-based development): 각 단계는 전용 디렉토리와 루트 CLAUDE.md를 확장하는 CLAUDE.<phase>.md 파일을 가집니다. 단계 게이트 (Phase gates)는 다음 단계로 넘어가기 전 필요한 최소 전제 조건을 정의합니다.
• 추적 가능성 (Traceability): 모든 산출물은 서술형 ID(GOAL-reduce-latency, REQ-F-search-by-name, DEC-use-postgres)를 통해 서로를 참조하며, 비즈니스 요구사항부터 실행 중인 코드까지 하나의 체인을 형성합니다. 인덱스 테이블은 산출물 파일로 직접 연결되어 탐색이 용이합니다.
• 두 파일 결정 방식 (Two-file decisions): 실행을 위한 활성 기록(DEC-kebab-name.md)과 감사 추적 (Audit trail)을 위한 히스토리 파일(DEC-kebab-name.history.md)로 구분합니다. 각 단계별로 트리거 조건과 함께 인덱싱됩니다.
• 컨텍스트 윈도우 효율성 (Context-window efficiency): 계층적 지침, 단계별 인덱스, 그리고 활성/히스토리 분리 방식을 통해 에이전트가 로드해야 하는 토큰(Token) 수를 최소화합니다.

스캐폴드(Scaffold)가 채워지는 방식

스캐폴드는 빈 상태로 시작합니다. 프로젝트별 산출물은 모든 것이 한꺼번에 만들어지는 것이 아니라, 각 단계를 진행함에 따라 점진적으로 생성됩니다.

• 프로젝트 시작 시 (/SDLC-init): 에이전트가 처음부터 올바른 컨텍스트를 가질 수 있도록 CLAUDE.md에 프로젝트 설명을 설정합니다.
• 명세 단계 (Specification phase) 동안 (/SDLC-elicit): 이해관계자, 목표, 제약 조건, 가정, 사용자 스토리 및 요구사항을 정의합니다.
• 설계 단계 (Design phase) 동안 (/SDLC-design): 아키텍처, 데이터 모델, API 설계를 초안합니다. 결정 사항은 설계 작업 중에 발생하는 대로 기록됩니다.
• 코드 단계 시작 시 (/SDLC-decompose, /SDLC-implementation-plan): 컴포넌트를 식별하고 (3-code/ 하위에 컴포넌트별 디렉토리 생성), 태스크 백로그 (Task backlog)를 생성합니다.
• 코드 단계 (Code phase) 동안 (/SDLC-execute-task, /SDLC-fix): 태스크를 하나씩 구현합니다 (각 호출은 기본적으로 다음 대기 중인 태스크를 선택하거나, 사용자가 제공한 컨텍스트를 사용하여 특정 태스크를 선택한 뒤 코드를 작성하고 테스트를 수행하며 태스크 상태를 업데이트합니다). 또는 버그 수정 및 필요에 따른 변경 사항을 적용합니다.

Claude skills는 라이프사이클 (lifecycle)의 각 단계를 자동화합니다. Claude Code에서 /skill-name을 입력하여 이를 호출할 수 있습니다. 각 스킬은 동작하기 전에 루트 디렉토리의 CLAUDE.md와 관련 단계별 지침을 읽습니다.

설정 (Setup)

스킬	목적
/SDLC-init	가이드 기반 프로젝트 초기화 — 에이전트(agents)가 시작부터 올바른 컨텍스트를 가질 수 있도록 CLAUDE.md에 프로젝트 설명을 설정합니다.

사양 단계 (Specification Phase)

스킬	목적
/SDLC-elicit	대화형 요구사항 도출 (requirements elicitation) — 정해진 순서에 따라 이해관계자(stakeholders), 목표, 가정, 제약 조건, 사용자 스토리(user stories) 및 요구사항을 안내합니다. 템플릿으로부터 산출물(artifacts)을 생성하고 인덱스를 업데이트합니다. 또한 기존 산출물에 대한 차이 분석 (gap analysis)을 수행합니다.

설계 단계 (Design Phase)

스킬	목적
/SDLC-design	승인된 요구사항을 기반으로 아키텍처 (architecture), 데이터 모델 (data model) 또는 API 설계 문서를 초안 작성하거나 업데이트합니다. 설계 완성도 평가를 포함합니다. 추적성 (traceability)을 위해 요구사항을 ID로 참조합니다.
/SDLC-decompose	설계 산출물로부터 별도의 소프트웨어 컴포넌트 (components)를 식별하고 3-code/ 아래에 컴포넌트별 디렉토리를 생성합니다. 설계 단계에서 코드 단계로 전환할 때 사용합니다.

코드 단계 (Code Phase)

스킬	목적
/SDLC-implementation-plan	설계 산출물로부터 단계별 구현 계획을 생성합니다. tasks.md에 점진적 개발 단계별로 그룹화된 짧은 태스크들을 채워 넣으며, 각 단계는 배포 및 테스트 가능한 시스템으로 종료됩니다.
...

교차 단계 (Cross-Phase)

스킬	목적
/SDLC-status	프로젝트 전반의 대시보드: 단계별 산출물 수, 태스크 진행 상황, 단계 게이트 (phase-gate) 준비 상태, 추적성 상태 및 평가 최신성.

일반적인 워크플로우 (Typical Workflow)

/SDLC-init                  ← 프로젝트 설정
/SDLC-elicit                ← 이해관계자, 목표, 요구사항 정의
                            ← 사람이 산출물 승인 (초안 → 승인됨)
...

라이선스 (License)

Apache License, Version 2.0에 따라 라이선스가 부여됩니다. LICENSE를 참조하세요.

기여(Contributions)는 동일한 라이선스 하에 허용됩니다 (inbound = outbound). CONTRIBUTING.md를 참조하세요.