name: dev-cycle-protocol description: Orchestrator of the role-based development cycle - phases from product inception (Phase 0) and discovery to a verified release, on the project's branching model (integration, trunk or release-branches), the role skill called in each phase (product-inception, software-design, quality-assurance, devops-release, user-docs, architecture-docs, plan-memory, code review), a full path for features and a short path for small fixes, the project backlog with epics and bugs before new work, the roadmap of releases, GitHub Spec Kit as the optional executor of specification, planning and implementation, the user's approval gates (product baseline, plan, release candidate acceptance, the release gate: merge into production or promotion of the candidate), the shared .dev-cycle.json project configuration and automated gate verification. Use during all product, software design, exploration, implementation, review and release tasks.

🛡️ 개발 주기 프로토콜 (`dev-cycle-protocol` v4)

경로: <skills_root>는 이 스킬이 포함된 폴더입니다(이 SKILL.md의 폴더 상위). 명령을 실행할 때 실제 절대 경로를 사용하세요. 프로젝트의 리포지토리에서 실행하세요(또는 --dir 전달): 클라우드 세션(/home/user 같은)에서 시작하면 잘못된 폴더를 읽게 됩니다.

엔진: 이미 Rust로 번역된 스크립트(IMP-005)는 런처를 통해 실행됩니다. 여기서는 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" <skill> <script> [args]로 작성합니다(sh 셸: Linux, macOS, Git Bash). PowerShell에서는 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" <skill> <script> [args]를 실행합니다. 첫 번째 실행 시 머신용 엔진을 다운로드하고 체크섬을 확인합니다.

**dev-cycle-protocol**은 마치 전문가 팀처럼 소프트웨어 작업을 오케스트레이션합니다. 단계, 게이트 및 각 역할이 언제 실행될지를 소유하며, 각 역할 스킬은 고유한 결과물, 규칙 및 검사기를 소유합니다. 이 프로토콜은 언어 및 프로젝트에 구애받지 않습니다.

언어: 사용자가 사용하는 언어로 대화하되, 모든 프로젝트 결과물은 영어로 작성하세요: 코드, 주석, 문서, ADR, 계획, 수동 테스트, 커밋 메시지 및 풀 리퀘스트 설명. 프로젝트는 .dev-cycle.json(architecture_docs.language)에서 다른 문서화 언어를 설정할 수 있습니다.

🧭 세션 시작 (`/dev-cycle`)

사용자는 하나의 명령어 /dev-cycle로 시작합니다(제품 아이디어나 요청을 포함하거나 단독으로). 이 명령어는 진단(onboard diagnose 엔진에서)을 실행하고, 프로젝트가 최신 상태임을 한 줄로 알린 후 계속 진행하거나 권장 순서대로 옵션을 표시합니다: 진행 중인 계획, 보류 중인 릴리스 후보, 열린 차단 버그, 누락된 설정(구성, 브랜칭 모델, 통합 브랜치, Spec Kit), 누락된 제품 기준선, 현재 릴리스의 다음 항목, 요청. 새 리포지토리는 0단계로 이동합니다. 프로토콜을 사용한 적이 없는 리포지토리는 한 번에 또는 항목별로 확인되는 초기 설정 목록을 받습니다. 사용자가 확인하기 전에는 아무것도 기록되지 않습니다. 사용자가 명령어 없이 작업을 요청하면 먼저 동일한 진단을 실행합니다.

👥 역할

역할	스킬	소유 영역
오케스트레이터	`dev-cycle-protocol`	단계, 게이트, 각 변경 사항의 경로, `.dev-cycle.json`, `/dev-cycle` 진단, Spec Kit 설정 및 생성된 헌장
제품	`product-inception`	0단계: 제품 기준선, `docs/product/VISION.md` 및 `TECH_SPEC.md`
기획자	`plan-memory`	에픽이 포함된 백로그(`docs/BACKLOG.md`, `/backlog` 명령어), 로드맵(`docs/ROADMAP.md`), `docs/plans`의 계획 파일, 마일스톤, 드리프트 감지
아키텍트	`software-design`	설계 원칙, 아키텍처 스타일, 계획의 설계 섹션, 구조적 리뷰
기술 문서	`architecture-docs`	`TECDOC.md`, `docs/architecture`, ADR
QA	`quality-assurance`	자동화된 테스트 전략, 큐레이팅된 수동 테스트 스위트, 릴리스 후보 실행
DevOps	`devops-release`	브랜칭 모델, CI, 버전, 릴리스 후보, 릴리스, 관찰 가능성
기술 문서 작성자	`user-docs`	README 및 최종 사용자 문서
리뷰어	`code-review`	플랫폼의 모든 풀 리퀘스트 리뷰: 수준이 포함된 라인 코멘트, 절대 승인하지 않음
세션 메모리	`session-memory`	개발자 자신의 세션 컨텍스트
Gedo 피드백 (임시, 기본적으로 비활성화)	`gedo-feedback`	실제 작업에서 Gedo에서 발생하는 문제를 기록하며, 프로젝트가 Gedo를 사용하는 동안(`gedo.enabled`) Gedo의 백로그에 기록됨
사양 실행기 (선택 사항)	GitHub Spec Kit	1, 2, 4단계에서 기능의 세부 사항: `specs/NNN-slug/` (사양, 계획, 작업)

역할은 별도의 사람이 아닌 일련의 규칙과 검사기입니다: 해당 단계가 시작될 때 역할 스킬을 로드하고, 그 지침을 따르며, 단계를 떠나기 전에 검사기를 실행하세요. Spec Kit은 도구이지 역할이 아닙니다: 프로토콜이 언제 실행되고 무엇을 생성하는지 결정합니다("Spec Kit" 참조).

🏛️ 원칙

설계: 명확한 책임, SOLID, Clean Code, 명시적 오류, 필요할 때만 패턴을 사용하는 모듈식 코드, 프로젝트의 아키텍처 스타일(software-design)을 따릅니다.
증거: 모든 변경 사항은 자동화된 테스트로 입증됩니다. 수동 테스트는 자동화할 수 없는 것만 하나의 큐레이팅된 스위트(quality-assurance)에서 다룹니다.
문서는 오늘을 설명합니다: 기술 문서와 README는 제자리에서 편집됩니다. 기록은 Git과 릴리스 노트(architecture-docs, user-docs)에 있습니다.
계획은 공유되고 완전합니다: 승인된 계획은 프로젝트(plan-memory)의 버전 관리된 파일입니다.
안전한 전달: 프로젝트의 브랜칭 모델에 있는 단기 브랜치, 모든 풀 리퀘스트의 CI, 릴리스 후보, 사용자의 릴리스 게이트(devops-release).
보안: Git에 비밀 없음, 이전 버전과 호환되는 데이터 마이그레이션, 모든 릴리스에 대한 롤백 경로.
버그 우선: 열린 critical, high, medium 버그는 새로운 기능, 개선 사항 및 조정보다 먼저 계획되고 수정됩니다. low 버그는 늦어도 다음 릴리스에 포함됩니다. 알려진 버그는 분류되지 않은 채로 남지 않습니다(심각도 및 차단되지 않는 버전에 대한 릴리스). 오직 사용자만이 명시적으로 위험을 수락할 수 있습니다. 발견된 것은 손실되지 않으며, 지금 수정되거나 백로그에 캡처됩니다.
완수: 에이전트는 CI와 릴리스를 끝까지 추적하고 실패하는 것을 수정합니다. 사용자의 결정(계획 승인, 후보 수락, 릴리스 게이트)은 절대 에이전트가 내리지 않습니다.
AI 귀속 금지, 모든 곳에서: 어떤 결과물도 AI, 모델 또는 코딩 에이전트를 작성자, 공동 작성자, 리뷰어 또는 출처로 명명하지 않습니다: 커밋 및 그 트레일러, 태그, 브랜치, 풀 및 병합 요청, 리뷰 및 리뷰 코멘트, 이슈, 계획, 문서, 릴리스 노트 및 코드 주석. 모든 것은 리포지토리의 Git ID(devops-release)가 작성합니다. 프로젝트가 도구에 필요한 구성(에이전트 설정 폴더, 통합 이름)은 기술적인 것이며 귀속이 아닙니다. pr_sync 이외의 도구(플랫폼 도구, 커넥터, 웹 페이지)를 통해 게시된 텍스트는 먼저 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol _no_ai --file <text>로 확인하고, 게시 후 다시 읽습니다: 도구가 추가한 푸터, 링크 또는 마커("Generated by ...", 에이전트 세션 또는 스레드 링크)는 즉시 편집됩니다. 게이트 8은 또한 작성자 또는 커미터가 AI ID인 커밋을 거부합니다.

🧭 경로 선택

경로	시기	단계
착수	아이디어에서 새 제품, 또는 제품 기준선 없이 기존 프로젝트(도입)	제품당 한 번 0단계, 이후 로드맵의 첫 번째 항목에 대한 전체 경로
전체	새 기능, 리팩터, 데이터 또는 스키마 변경, 명령어, 구성, 파일 형식 또는 공개 API 변경, CI/릴리스 변경, 여러 모듈에 걸친 모든 것	변경당 1~~7단계, 릴리스당 8~~10단계
짧은	소규모 버그 수정, 문서 전용, 테스트 전용 또는 오타 변경으로, 하나의 작은 풀 리퀘스트에 들어가고 인터페이스나 데이터를 변경하지 않는 경우	1, 4, 5, 6단계(영향받은 부분만), 7단계

짧은 경로의 경우, 사용자의 요청이 변경 사항을 명명할 때("X에서 충돌 수정") 승인이 됩니다. 그렇지 않으면 변경 사항을 한두 문장으로 설명하고 사용자의 진행을 기다리세요. 의심스러운 경우 전체 경로를 사용하세요.

🔄 주기

graph TD
    P0["0. 제품 착수 (한 번)<br/>product-inception, 게이트 0 (사용자)"] -.-> P1
    P1["1. 발견<br/>orchestrator, plan-memory, software-design"] --> P2["2. 계획<br/>plan-memory + 모든 역할"]
    P2 --> G3{"3. 계획 승인<br/>(사용자)"}
    G3 -- "질문 / 변경" --> P1
    G3 -- "승인됨" --> P4["4. 브랜치에서 구현<br/>software-design"]
    P4 --> P5["5. 자동화된 테스트<br/>quality-assurance"]
    P5 --> P6["6. 문서화<br/>architecture-docs, user-docs, quality-assurance"]
    P6 --> P7["7. 리뷰 및 작업 기준선으로 PR, CI 통과<br/>reviewer, software-design, devops-release"]
    P7 -. "다음 변경" .-> P1
    P7 --> P8["8. 릴리스 후보<br/>devops-release, quality-assurance"]
    P8 --> G9{"9. 수락<br/>(사용자가 수동 테스트 실행)"}
    G9 -- "실패 / 차단됨" --> P4
    G9 -- "모두 통과" --> G10{"10. 릴리스 게이트 (사용자)<br/>dev를 main에 병합하거나 후보 승격"}
    G10 --> P11["최종 릴리스 추적 및 확인<br/>devops-release, plan-memory, session-memory"]

0단계는 제품당 한 번 실행됩니다. 1~~7단계는 모든 변경 사항에 대해 실행됩니다. 8~~10단계는 사용자가 작업 기준선에 축적된 내용을 릴리스하려고 할 때 실행됩니다.

브랜칭 모델 (devops.branching, devops-release): 아래 모든 단계는 작업 기준선, 후보 브랜치 및 릴리스 게이트를 말합니다. 모델이 이들을 제공합니다(엔진의 branching show: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" devops-release branching show):

모델	작업 기준선(브랜치 생성, PR 대상)	후보 브랜치	릴리스 게이트 (사용자)
`integration` (기본값)	`dev`	`dev`	`dev`를 `main`에 병합
`trunk`	`main`	`main`	수락된 후보의 프로모션 워크플로 실행
`release-branches`	`main` (릴리스 수정: `release/X.Y`)	`release/X.Y`	수락된 후보의 프로모션 워크플로 실행

0. 🌱 제품 착수 (제품당 한 번)

product-inception을 따릅니다: 인터뷰, 비즈니스 문서, 아키텍처, 기술 사양, 헌장(Spec Kit), 에픽이 있는 제품 백로그, 로드맵, 각각 사용자 승인. 이는 게이트 0, 즉 사용자의 제품 기준선 승인으로 끝납니다:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 0

이미 진행 중인 기준선이 없는 프로젝트는 이를 도입(도입 모드)하거나 건너뛸 수 있습니다: 0단계는 새 제품에 필수이며, 기존 제품에는 권장됩니다.

1. 💡 발견

상담 태도를 유지하세요: 사용자가 질문, 토론 또는 제안하는 동안 파일을 편집하거나 코드를 시작하지 마세요.

프로젝트 및 구성을 검사하세요:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol inspect_project
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol project_config --validate

로그 먼저: 보고된 오류에 대해 가설을 세우기 전에 실제 로그를 읽으세요.
활성 계획을 읽으세요(엔진의 list_plans: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans; plan-memory check_milestone --list). 그리고 아키텍처 스타일 및 구조(software-design)를 읽으세요.
백로그와 로드맵을 읽으세요(엔진의 plan-memory backlog summary, roadmap current: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap current; inspect_project는 둘 다 표시합니다). 새 작업보다 먼저 열린 버그를 사용자에게 보여준 다음, 현재 릴리스의 열린 항목과 요청과 관련된 항목을 보여줍니다. 사용자는 무엇을 승격, 재우선순위화, 이동 또는 드롭할지 결정합니다("백로그 및 로드맵" 참조).
백로그 항목을 계획하려면 승격하세요(backlog promote <ID> ...): 발견 내용이 기록되는 곳은 초안 계획(버그의 경우 버그 계획)입니다.
Spec Kit: 작업 기준선을 체크아웃한 다음, 항목 설명과 함께 /speckit-specify를 실행하세요: 작업 브랜치 feat/NNN-slug와 specs/NNN-slug/spec.md를 생성합니다. [NEEDS CLARIFICATION] 마커가 남지 않을 때까지 /speckit-clarify를 실행하세요. 사용자가 질문에 답변합니다. 승격된 계획은 봉투이고 발견은 사양에 있습니다.
미해결 질문을 모두 소진하고 사용자와 접근 방식에 대해 수렴하세요.

2. 📋 계획

이 템플릿을 사용하여 완전한 계획을 작성하고 각 역할의 섹션을 수집하세요:

목표 및 결정: 무엇이 변경되는지와 그 이유 결정 및 대안은 ADR(architecture-docs)이 됩니다.
설계 (software-design): 각 조각이 위치한 곳, 인터페이스, 데이터 흐름, 오류 전략, 종속성, 의도적으로 추상화되지 않은 것.
영향받는 표면 및 파일: 변경되는 architecture.surfaces의 인터페이스, 파일 및 모듈.
테스트 (quality-assurance): 추가할 자동화 테스트(버그당 회귀 테스트 하나), 추가, 변경 또는 제거할 수동 테스트, 수락 기준.
문서화 (architecture-docs, user-docs): 서브시스템 페이지 및 ADR, README 섹션.
CI, 릴리스 및 관찰 가능성 (devops-release): 워크플로 변경, 버전 영향, 추가할 로그, 진단 및 원격 측정과 테스트 방법.
보안, 마이그레이션 및 롤백: 비밀, 데이터 마이그레이션(이전 버전과 호환), 롤백 방법.
실행 단계 및 마일스톤.

Spec Kit: /speckit-plan을 실행하세요(그 계획은 작업을 specs/NNN-slug/에 나눕니다).

3. 🚧 계획 승인

게이트 3, 사용자:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 3

계획 승인 이전: 에이전트는 변경 사항의 전체 계획을 작성하고, 모든 역할의 섹션을 포함하며, 새 작업(plan-memory)의 백로그 항목을 업데이트하고, 게이트를 확인합니다. 사용자는 검토하고 승인하거나 변경을 요청합니다. 변경이 필요한 경우 발견 단계로 돌아가거나 계획을 업데이트하고 다시 제출합니다.

4. 💻 구현

승인된 계획의 실행 단계를 따르세요.
작업 기준선에서 브랜치를 생성하세요 (모델에 따라 dev (integration), main (trunk), release/X.Y (release-branches)). 브랜치 이름: feat/NNN-slug, fix/NNN-desc 또는 refactor/XXX.
전용 /spec-kit 명령어, software-design, quality-assurance, devops-release를 사용하세요.
Spec Kit: /speckit-implement (사양의 각 작업을 코드로 변환).

5. ✅ 자동화된 테스트

quality-assurance에 정의된 전략을 따르세요.
plan-memory(plan-memory test list)에서 계획된 모든 테스트를 실행하거나 확인 가능한 방식으로 실행하세요.
테스트가 실패하면 구현 단계로 돌아가서 고치세요.
Spec Kit: /speckit-verify (Spec Kit의 사양에 대한 자동화된 테스트를 실행).

6. 📝 문서화

계획에 따라 문서를 편집하세요.
architecture-docs 및 user-docs를 사용하세요.
README 업데이트, 아키텍처 다이어그램, ADR, 수동 테스트 스위트.

7. 🔍 리뷰 및 PR

변경 사항을 커밋하고 작업 기준선으로 PR을 생성하세요.
PR 설명을 작성하세요(변경 사항 요약, 계획 참조, 테스트 결과, 문서화 참조).
code-review를 사용하여 PR을 리뷰하세요: 라인 코멘트, 수준(blocker, important, suggestion). 절대 승인하지 마세요.
CI가 통과할 때까지 기다리세요. 실패하면 수정하고 강제 푸시하세요.
리뷰어가 변경을 요청하면 구현으로 돌아가세요.
Spec Kit: /speckit-pr (Spec Kit 사양에 대한 PR을 생성).

8. 🚀 릴리스 후보

devops-release의 지침을 따르세요.
후보 브랜치를 생성하세요(모델에 따라 dev, main, release/X.Y).
태그를 생성하세요: rc-<version>-<timestamp>.
quality-assurance 수동 테스트 스위트를 실행할 준비를 하세요.
사용자가 수동 테스트를 실행합니다.

9. 🎯 수락

게이트 9, 사용자:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 9

사용자는 수동 테스트를 실행하고 결과를 보고합니다. 모든 테스트가 통과하면 수락되고, 실패하거나 차단되면 구현 단계로 돌아갑니다.

10. 🔐 릴리스 게이트

게이트 10, 사용자만:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol verify_gate --gate 10

사용자는 Git 명령어나 워크플로를 사용하여 릴리스합니다. integration 모델: dev를 main에 병합. trunk 또는 release-branches 모델: 프로모션 워크플로를 실행합니다. 사용자는 릴리스를 트리거하는 사람입니다; 에이전트는 병합하거나 프로모션하지 마세요.

11. ✅ 최종 확인

devops-release가 릴리스를 프로덕션에 배포했는지 확인하세요.
plan-memory가 릴리스 노트를 업데이트하고 완료된 항목을 표시하세요.
session-memory가 세션 컨텍스트를 업데이트하세요.

📋 백로그 및 로드맵

plan-memory는 백로그(docs/BACKLOG.md)와 로드맵(docs/ROADMAP.md)을 관리합니다.

백로그 명령어:

backlog list: 모든 열린 항목 표시
backlog summary: 요약
backlog promote <ID> ...: 항목을 계획 상태로 승격
backlog add <title> [--description <desc>] [--priority <p>]: 새 항목 추가
backlog close <ID>: 항목 닫기

로드맵은 마일스톤과 릴리스 날짜를 보여줍니다. 새 작업을 시작하기 전에 항상 열린 버그를 검토하세요.

⚙️ 구성 (`.dev-cycle.json`)

프로젝트 루트에 있는 .dev-cycle.json 파일:

{
  "version": 1,
  "project": {
    "name": "프로젝트 이름",
    "language": "en",
    "architecture": {
      "style": "모듈식 모놀리스",
      "surfaces": ["REST API", "CLI"]
    }
  },
  "devops": {
    "branching": "integration",
    "ci": "github-actions",
    "versioning": "semver"
  },
  "speckit": {
    "enabled": true
  }
}

엔진을 사용하여 구성을 검증하세요:

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" dev-cycle-protocol project_config --validate

개발 주기 프로토콜