spec_driven_develop
무엇인가
Spec-Driven Develop은 아키텍처 우선 원칙으로 대규모 소프트웨어 변경을 스펙 주도 루프로 규율하는 Markdown 워크플로 묶음이다. 저장소는 상호 보완적인 세 스킬을 담는다. 대규모 작업의 전체 파이프라인을 자동화하는 Spec-Driven Develop, 다단계 사고로 문제 분석·브레인스토밍·해법 설계를 진행하는 Deep Discuss, 커밋되지 않은 변경·기간 커밋·브랜치/PR diff를 버그와 회귀 중심으로 검토하는 Review SPD(review-spd)다.
어떻게 동작하나
동작은 스킬 호출로만 이뤄진다. 슬래시 명령은 쓰지 않고 각 워크플로는 SKILL.md 형식의 스킬 파일로 정의된다. 대규모 변경 요청이 들어오면 7단계 파이프라인(Phase 0~6)이 발동한다. 의도 캡처, S.U.P.E.R 건강도 평가를 포함한 심층 분석, 분석에 근거한 의도 정제, 단계·태스크·병렬 레인 분해, MASTER.md 진행 추적, 확인 후 실행, 아카이브 순이다. 실행은 오케스트레이터 중심이며 Tier 0 직접 실행이 기본이고, 컨텍스트가 큰 배치는 task-executor(Tier 1), 파일 집합이 겹치지 않고 검증이 독립적인 경우에만 병렬 레인(Tier 2, 최대 4개)을 쓴다. 리뷰도 L1 기계 검증과 L2 오케스트레이터 diff 검토가 기본이고 L3 code-reviewer는 Tier 2 레인과 고위험 변경에 한정된다. 모든 문장을 규칙·계약·포인터 중 하나로 쓰고 주제마다 정본 참조를 하나만 두는 단일 출처 스타일 규칙을 따른다.
무엇과 다른가
프롬프트를 직접 쓰거나 CLAUDE.md·AGENTS.md 한 파일에 규칙을 몰아넣는 방식과 구조가 다르다. 단계별 산출물이 남고, GitHub 저장소가 감지되면 태스크마다 이슈를 만들고 Milestone·Label·Projects 보드로 묶는다. 구현 전에는 이슈 집합을 의존성·공유 파일·검증·리뷰 범위·롤백 경계 기준으로 배달 배치로 재편성하고, 이슈 단위가 아니라 단계당 하나의 통합 PR을 기본으로 삼는다. PR에는 완료된 이슈마다 Closes #N 한 줄이 들어가며, 단일 이슈 PR이나 분리 PR은 리뷰·릴리스·소유권·위험 격리·의존성·저장소 정책 사유를 문서로 남겨야 한다. 공학 제어론에서 착안한 폐루프 피드백 제어로 실행 중 계획을 조정한다.
어떻게 쓰나
설치와 적용은 Markdown 스킬을 읽는 경로에 두는 방식이다. 저장소에 포함된 scripts/install-agents.sh가 번들 스킬을 ~/.agents/skills로 동기화하며, 해당 공유 디렉터리를 읽는 에이전트는 이 경로로 붙인다. 첫 사용은 "이 프로젝트를 Rust로 다시 써라", "마이크로서비스 아키텍처로 마이그레이션하라" 같은 대규모 변경 요청을 던지는 것으로 시작한다. Phase 0이 방향을 1~2문장으로 잡고, Phase 2에서 분석에 근거한 질문으로 범위·우선순위·제약을 확정한 뒤, Phase 5에서 계획 요약을 제시하고 확인을 받아 실행한다.
전제와 한계
Claude Code, Codex, OpenCode, Cursor를 비롯해 사용자 정의 스킬을 읽는 Markdown 지원 에이전트에서 동작한다. SDK나 서드파티 런타임 의존성이 없다. GitHub 기능은 gh CLI가 없거나 저장소가 GitHub에 없으면 로컬 전용 모드로 자동 강등된다. 병렬 레인은 파일 집합이 겹치지 않고 레인당 L 이상 노력, 독립 검증 가능, 4개 이하 조건을 모두 만족할 때만 허용된다. 승인(APPROVED) 또는 수정 완료(FIXED)된 레인만 통합된다.