Claude Code와 명세를 사용한 AI 개발을 위한 FullSpec 프레임워크

# FullSpec: Claude Code 기반 AI 주도 개발 프레임워크

AI 보조 개발은 통합된 아키텍처 문서가 없으면 종종 혼란에 빠지기 쉽습니다. FullSpec은 아이디어에서 릴리스까지 전체 라이프사이클을 AI 에이전트가 생성하고 유지하는 명세 체인으로 형식화하여 이 문제를 해결합니다.

문제점: 아키텍처 메모리가 없는 AI

Claude Code 같은 LLM의 핵심 도전 과제는 아키텍처 결정에 대한 맥락 부재입니다. AI는 코드를 빠르게 뽑아내지만, 시스템이 왜 그렇게 구축되었는지 잊어버립니다. 25개의 마이크로서비스 프로젝트에서 이는 주요 충돌을 일으킵니다:

• 인접 서비스 간 일관되지 않은 암호화 알고리즘
• 맞지 않는 API 계약
• 병렬 세션에서 발생하는 상충되는 결정

전통적인 문서는 부족합니다: 업데이트되지 않거나 관료적 절차에 묻히기 때문입니다. AI에게는 최신이고 완전하며 모순 없는 명세가 필요하며, FullSpec이 바로 그 환경을 제공합니다.

FullSpec 아키텍처: 23개 에이전트와 8단계

이 프레임워크는 AI 에이전트가 생성하고 검증하는 형식 문서로 개발을 구조화합니다. 사용자는 "OAuth2 인증 구현" 같은 작업 설명으로 /chain을 트리거하면 8단계 시퀀스가 시작됩니다.

명세 레벨

체인은 각 단계에서 필수 검토와 함께 4단계 문서 레벨을 생성합니다:

• 토론 — 요구사항, 성공 기준, 범위, 위험
• 설계 — 시스템 변경: 서비스, API 계약, 데이터 모델
• 테스트 계획 — 코드 작성 전 테스트 시나리오
• 개발 계획 — 작업, 의존성, 실행 블록

명세가 승인되면 시스템이 자동으로 문서를 생성하고, GitHub 이슈를 만들며, 코드와 테스트를 작성하고, 코드 리뷰를 실행하며, PR을 빌드합니다.

주요 프레임워크 메커니즘

병렬 에이전트 워크플로

하나의 Claude가 순차적으로 작업을 처리하는 대신, FullSpec은 23개의 전문 AI 에이전트를 배포합니다:

• 설계 생성기
• 테스트 플래너
• 다양한 언어 코더
• 모든 레벨 리뷰어
• 문서 동기화 에이전트

동기화 중에는 서비스당 하나의 에이전트를 병렬로 N개 띄웁니다.

자동 검증과 규칙

시스템은 80개 이상의 검증 스크립트와 30개의 pre-commit 훅을 탑재하여 다음을 확인합니다:

• 문서 형식
• 구조적 일관성
• 코드 내 비밀 누출 없음
• 커밋 메시지 표준

파일 타입당 16개의 맥락 규칙이 자동 로드됩니다: .ts → TypeScript 표준, .py → FastAPI 표준. 규칙은 .claude/rules/에 있으며 추가 프롬프트 없이 원활하게 적용됩니다.

살아있는 명세와 충돌 검사

경쟁자와 차별화되는 점: 시스템이 코드-명세 불일치를 감지하고 수정합니다. 커밋 후 CONFLICT-CHECK가 실행됩니다:

• 모순 시 중단
• 충돌 레벨(설계, 개발 계획 등) 특정
• 상위에서 하위로 명세 업데이트 연쇄
• 모든 개발 단계에서 문서 최신 유지

대안 비교

| 기준 | FullSpec | Spec Kit (GitHub) | Kiro (AWS) | OpenSpec (Fission AI) |

|------|----------|-------------------|------------|-----------------------|

| 유형 | 프로세스 프레임워크 | CLI 툴킷 | IDE (VS Code 포크) | CLI 프레임워크 |

| 요구사항 형식화 | 기준 포함 토론 | 헌장 + 명세 | 요구사항 (EARS) | 제안 |

| 아키텍처 설계 | API 계약 포함 설계 | 계획 | 설계 (마크다운) | 설계 |

| 코드 전 테스트 계획 | TC-N 번호 테스트 계획 | 없음 | 없음 | 없음 |

| 충돌 감지 | 자동 + 연쇄 업데이트 | 없음 | 없음 | 없음 |

| 살아있는 문서 | 명세에서 자동 동기화 | 없음 | 없음 | 없음 |

| GitHub 자동화 | 이슈, PR, 리뷰, 릴리스 | 없음 | 없음 | 없음 |

| AI 에이전트 | 23개 병렬 | 0 | 1개 (내장) | 0 |

| 검증 | 80+ 스크립트, 30 pre-commit 훅 | 0 | 0 | ~5 |

| 기존 프로젝트 지원 | 아직 미지원 | 지원 | 지원 | 지원 (주요) |

FullSpec은 전체 개발 사이클을 커버하지만 Claude Code에 종속적이며 현재 기존 프로젝트 통합이 부족합니다.

기술 사양

• 71개 스킬 — 모든 프로세스 단계 슬래시 명령
• 23개 AI 에이전트 — 전문 병렬 워커
• 80+ 검증 스크립트 — 모든 단계 검사
• 30개 pre-commit 훅 — 자동 품질 관리
• 16개 맥락 규칙 — 신기술 확장
• 8개 프로세스 단계 — 아이디어에서 프로덕션 릴리스
• 재귀 표준화 — 자체 규칙으로 자기 구축

주요 요점

• 낮은 진입 장벽 — 내부는 복잡하지만 사용자는 /chain 실행하고 채팅으로 확인만
• Claude Code 전용 — 이 AI용 제작; 다른 AI 미검증
• 러시아어 문서 — 지침과 명세 러시아어지만 Claude가 잘 처리
• 신규 프로젝트 전용 — 새 프로젝트 템플릿으로 작동; 기존 프로젝트 개발 중
• 오픈 소스 — GitHub에서 MIT 라이선스

이 프로젝트는 AI가 단순히 코드를 뱉는 게 아니라 형식화된 프로세스와 살아있는 문서 속에서 번영하는 접근을 실현합니다. 아키텍처 위험을 줄이고 AI 활용 팀의 예측성을 높입니다.

— Editorial Team