aws-samples/sample-specship
요약
Kiro Power의 SpecShip은 역공학부터 배포까지 이어지는 자율 엔지니어링 워크플로우를 제공합니다. TDD와 적대적 검증을 결합하여 AI 에이전트가 생성한 코드의 품질을 보장하는 파이프라인을 구축합니다.
핵심 포인트
- RECON-PLAN-BUILD-VALIDATE-SHIP의 5단계 파이프라인 제공
- TDD(테스트 주도 개발)를 통한 엄격한 품질 게이트 적용
- 7개의 전문 서브 에이전트를 활용한 병렬 적대적 검증 수행
- Brownfield 환경을 위한 코드 역공학 및 영향 분석 기능
Kiro Power의 자율 엔지니어링 워크플로우로, brownfield 역공학 (reverse engineering), TDD (Test-Driven Development), 병렬 실행 (parallel execution), 적대적 검증 (adversarial validation), 그리고 명세 기반 품질 게이트 (spec-driven quality gates)를 포함하는 완전한 recon → plan → build → validate → ship 파이프라인을 통해 AI 에이전트들을 오케스트레이션합니다.
편집 가능한 소스: docs/architecture-diagram.svg
| 단계 | 수행 내용 | 결과물 |
|---|---|---|
| RECON (brownfield 전용) | 계획 수립 전 기존 코드를 역공학 (reverse engineer): 리포지토리 맵 (repo map), 기술 스택 (technology stack), 컴포넌트 (components), API, 데이터 모델 (data models), 비즈니스 흐름 (business flows), 베이스라인 테스트 (baseline tests), 보존된 동작 (preserved behavior), 그리고 변경 영향 (change impact). | .specship/.../artifacts/reverse-engineering/ |
| PLAN | 브레인스토밍 → 시장 조사 (실제 웹 검색, 최소 5개 쿼리) → 스프린트 계약 (sprint contract) → 테스트 케이스 사전 생성 (pre-generate test cases) → 구현 계획 (implementation plan). 각 단계는 다음 단계로 이어집니다. | requirements.md + design.md + tasks.md + artifacts |
| BUILD | tasks.md를 마일스톤별로 실행. 독립적인 작업에 대해 병렬 배치 (parallel batches) 수행. 모든 동작은 테스트 주도 개발 (TDD, 실패하는 테스트 작성 → 실패 확인 → 구현 → 통과 → 커밋)을 따릅니다. 타입 체크 (typecheck) + 테스트 + 빌드가 통과될 때까지 엄격한 게이트 (hard gate)가 각 마일스톤을 차단합니다. | 마일스톤별로 테스트되고 커밋된 코드 |
| VALIDATE | 최대 7개의 적대적 검증기 (adversarial validators)가 독립적인 서브 에이전트 (subagents)로서 병렬로 실행되며, 각 에이전트는 자신의 gstack 전문 기술(code→review, security→cso, browser→qa-only)에 위임합니다. 코드 (Code), 보안 (Security), 통합 (Integration), 브라우저 (Browser), 디자인 (Design), 정렬 (Alignment, 항상 포함) + 부하 (Load, 성능 NFR이 존재하는 경우). 각 검증기는 증거와 함께 타입화된 판결 (typed verdict)을 생성합니다. 집계 결과에 따라 결정: 병합 (merge) / 복구 (recover) / 에스컬레이션 (escalate). | 타입화된 판결 → 병합 또는 복구 |
| SHIP | PR + 변경 로그 (changelog) + 아카이브 (archive). 소요 시간, 발견된 버그, 마일스톤 세부 내역이 포함된 배포 보고서 (ship report). git 원격 저장소가 없는 경우, 푸시(push) 지침과 함께 로컬에서 준비합니다. | 병합 준비가 된 PR |
AI 에이전트는 빠르지만 얕게 구축합니다 — 7분 만에 작동하는 스켈레톤 (skeleton)을 만들지만, 기능의 60%가 누락되고, 테스트가 없으며, 에러 핸들링 (error handling)도 없습니다. SpecShip은 이를 해결합니다:
| 원칙 (Principle) | 의미 (What it means) |
|---|---|
| 테스트 주도 개발 (Test-Driven Development) | 실패하는 테스트 없이 프로덕션 코드를 작성하지 않습니다. 타입 체크 (typecheck) + 테스트 + 빌드가 모두 통과될 때까지 빌드 게이트 (build gate)가 모든 마일스톤을 차단합니다. 버그를 몇 시간이 아닌 몇 분 내에 잡아냅니다. |
| 병렬 실행 (Parallel execution) | 독립적인 작업들이 동시에 실행됩니다. 모든 검증기 (validators)가 독립적인 서브 에이전트 (subagents)로서 병렬로 작동합니다. 한 시간 분량의 순차적 작업이 몇 분 만에 완료됩니다. |
| 적대적 검증 (Adversarial validation) | 코드를 작성한 에이전트는 해당 코드를 심사할 수 없습니다. 독립적인 검증기들이 증거와 함께 타입이 지정된 판결 (typed verdicts)을 내립니다. 자체적인 방법론을 가진 별도의 기술이 코드를 심사합니다. |
| 자가 치유 복구 (Self-healing recovery) | 검증기가 버그를 발견하면, 새로운 에이전트가 이를 정밀하게 수정합니다 — 이슈당 한 번의 수정, 회귀 테스트 (regression test) 우선, 최대 3회 사이클 이내. 서로 다른 파일을 수정할 때는 병렬로 수정합니다. |
| 계약 우선 (Contract-first) | 모든 빌드는 수락 기준 (acceptance criteria) + 실패 모드 (failure modes) + 설계 사양 (design spec)과 함께 시작됩니다 — 이는 코드가 작성되기 전에 정의되며 .specship/specs/<id>/requirements.md 및 design.md에 저장됩니다. 검증기는 느낌 (vibes)이 아닌 계약 (contract)을 기준으로 심사합니다. |
| 브라운필드 안전성 (Brownfield-safe) | 기존 코드는 계획을 세우기 전에 역공학 (reverse-engineered) 과정을 거칩니다. 계약에는 보존된 동작, 로컬 컨벤션 (local conventions), 베이스라인 테스트 (baseline tests), 변경 가능성이 높은 파일, 그리고 피해야 할 파일이 포함됩니다. |
| 시장 조사 (Market research) | 동일한 카테고리의 기존 제품을 연구하기 위해 실제 웹 검색 (최소 5개 쿼리)을 수행합니다. 학습 데이터나 튜토리얼이 아닌, 기존에 존재하는 것들을 기준으로 품질 기준을 설정합니다. 조사 결과는 .specship/specs/<id>/artifacts/market-research.md에 저장됩니다. |
./install.sh
끝입니다. 설치 프로그램은 자동으로 다음을 수행합니다:
- 누락된 의존성 (dependencies) 감지 및 설치 (superpowers + gstack)
- SpecShip 스티어링 (steering) 파일들을
~/.kiro/steering/로 복사 - Playwright MCP 설정 여부 감지 — 설정되어 있지 않다면 설정 (Node.js가 누락된 경우 가이드 포함)
명령어 하나로 모든 설정이 완료됩니다.
기본적으로 전역(globally)으로 설치됩니다 (~/.kiro/steering/). 단일 프로젝트로 범위를 제한하려면 ./install.sh ./.kiro/steering을 사용하세요.
그저 Kiro에게 말만 하세요 — auto 기술이 당신의 의도에 맞게 작동합니다:
SpecShip을 사용하여 칸반 보드(Kanban board)를 만들어줘
결제 기능을 추가하기 전에 이 저장소(repo)를 역공학(reverse engineer)해줘
빌드 시작
...
특정 기술(skill)을 강제하고 싶나요? 해당 슬래시 명령어(/specship-plan, /specship-validate)를 입력하거나 #를 사용하여 참조(#specship-plan)하세요.
kiro-power-specship/
├── power.json # Power 매니페스트 (manifest)
├── POWER.md # 전체 문서 (Try power 시 표시됨)
...
| 모드 (Mode) | 트리거 (Trigger) | 동작 (Behavior) |
|---|---|:|
| 가이드형 (Guided, 기본값) | Using SpecShip, build me X | 파이프라인(pipeline)을 실행하며, 빌드 전 계획 승인을 위해 일시 중지함 |
| 자율형 (Autonomous) | SpecShip auto: build me X 또는 build me X, fully autonomous | 중단 없이 전체 파이프라인을 엔드 투 엔드(end-to-end)로 실행함. 사용자는 완료된 PR(Pull Request)을 확인하면 됨 |
SpecShip을 베이스라인(baseline)으로 삼고 그 위에 자신만의 워크플로(workflow)를 구축하세요. 업데이트하려면 ./install.sh를 다시 실행하세요 (덮어쓰기 전에 편집한 모든 파일을 백업합니다). 모든 것을 제거하려면 ./uninstall.sh를 실행하세요.
실험적이며 비공식적입니다. SpecShip은 외부 보안 검토를 거치지 않았으며 보증 없이 있는 그대로(as-is) 제공됩니다 — 사용 시 발생하는 위험은 사용자 본인에게 있습니다. 생성된 모든 코드는 샘플/참조 구현이며, 프로덕션(production) 사용 전 앱 보안(AppSec) 검토가 필요합니다. MIT 라이선스(MIT License) 하에 배포됩니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기