Dimon94/cc-devflow

로드맵 (roadmap), 계획 (planning), 조사 (investigation), 구현 (implementation), 검증 (verification), 그리고 배포 (shipping)를 위한 에이전트 우선 개발 워크플로우 (Agent-first development workflow).

중문 문서 | English | 시작하기 | 기여하기 | 보안

CC-DevFlow는 에이전트 코딩 (agent coding)을 위한 작고 명시적인 워크플로우 (workflow) 시스템입니다. 이 시스템은 AI 에이전트에게 하나의 로드맵 (roadmap) 진입점을 제공하며, 모든 변경 사항이 작업 완료로 간주되기 전에 기능 루프 (feature loop) 또는 버그 조사 루프 (bug-investigation loop)를 거치도록 경로를 지정합니다.

작은 공개 접점 (Small public surface): 핵심 워크플로우 기술, PR 하네스 (PR Harness) 레인, 하나의 선택적 심층 리뷰 (deep review) 기술, 그리고 설치 및 플랫폼 적응을 위한 CLI.
완료 전 증거 (Evidence before done): 구현 사항은 배포 (shipping) 또는 인계 (handoff) 전에 반드시 검증 증명 (verification proof)을 통과해야 합니다.
기술 우선 배포 (Skill-first distribution): 공개 계약 (public contract)은 숨겨진 런타임 동작이 아니라 .claude/skills/<skill>/SKILL.md 및 PLAYBOOK.md에 존재합니다.
멀티 플랫폼 출력 (Multi-platform output): 한 번 설치하면 Codex, Cursor, Qwen, Antigravity 및 관련 에이전트 (agent) 환경에 맞게 적응할 수 있습니다.
지속 가능한 프로젝트 메모리 (Durable project memory): 로드맵 (roadmap), 사양 (specs), 계획 (planning), 리뷰 (review), 인계 (handoff) 산출물은 devflow/에 유지되며, 임시 작업자 스크래치 (temporary worker scratch)는 지속 가능한 진실 (durable truth) 외부에 유지됩니다.

사전 요구 사항:

Node.js 18+
npm 또는 호환 가능한 패키지 러너 (package runner)
Git 리포지토리 (repository)
Claude Code 또는 기타 지원되는 에이전트 (agent) 환경

전체 기술 팩 설치:

npx cc-devflow@latest init --dir /path/to/your/project

플랫폼 출력 생성:

npx cc-devflow@latest adapt --cwd /path/to/your/project --platform codex
npx cc-devflow@latest adapt --cwd /path/to/your/project --platform cursor
npx cc-devflow@latest adapt --cwd /path/to/your/project --platform qwen
...

지원되는 모든 플랫폼 출력 새로고침:

npx cc-devflow@latest adapt --cwd /path/to/your/project --all

설치 후, 에이전트 (agent)에게 워크플로우 기술을 직접 사용하도록 요청하십시오. 제품 방향 설정을 위해 cc-roadmap으로 시작하십시오. 로드맵을 인식하는 다음 목표를 선택하려면 cc-next를 사용하고, 원격 PR이 열릴 때까지 PDCA 또는 IDCA를 통해 현재 워크트리 (worktree)를 구동하려면 cc-dev를 사용하며, cc-pr-review를 사용하십시오.

별도의 세션에서 해당 PR (Pull Request)을 검토하려면 cc-pr-review를 사용하며, 검토된 PR을 main 브랜치에 반영(land)하려면 cc-pr-land를 사용하십시오. 수동적인 코어 워크플로 (core workflow) 작업을 위해서는 cc-plan을 사용하십시오.

새로운 작업을 위해서는 cc-investigate를 사용하십시오.

버그의 경우, 복잡한 고정된 계획 (frozen plans) 또는 조사 (investigations) 단계에서 선택적으로 cc-review를 실행한 다음, cc-do를 통해 계속 진행하십시오.

선택적인 구현 단계로는 cc-review, cc-check, 그리고 cc-act가 있습니다.

cc-roadmap
PR Harness: cc-next -> cc-dev -> cc-pr-review -> cc-pr-land
PDCA: cc-plan -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
...

flowchart TD
Roadmap["cc-roadmap\n제품 방향 및 단계별 진실 (staged truth)"] --> Next["cc-next\n다음 준비된 Goal Packet 선택"]
Next --> Dev["cc-dev\n현재 워크트리 (worktree)를 PR로 구동"]
...

기술 (Skill)	사용 시점	주요 결과물
`cc-roadmap`	제품 방향, 단계별 범위 (staged scope), 또는 백로그 (backlog) 순서가 필요한 경우	`devflow/roadmap.json`, `devflow/ROADMAP.md`, (사용 중단된) `devflow/BACKLOG.md`
`cc-next`	로드맵, 아카이브되지 않은 로컬 변경 사항, 그리고 이슈 진실 (issue truth)로부터 로드맵을 인지하는 다음 준비된 목표를 선택해야 하는 경우	`cc-dev`를 위한 하나의 Goal Packet
`cc-dev`	선택된 목표를 현재 워크트리에서 원격 PR로 구동해야 하는 경우	`task.md`, Git 커밋, 그리고 PR 또는 인계 (handoff)
`cc-plan`	기능 또는 변경 사항에 대해 범위 (scope), 설계 (design), 그리고 작업 고정 (task freezing)이 필요한 경우	`task.md#Contract Summary`
`cc-investigate`	버그에 대해 증상 (symptom), 재현 (reproduction), 근본 원인 (root cause), 그리고 수정 범위 (repair boundary)를 파악해야 하는 경우	`task.md#Root Cause Contract`
`cc-do`	계획되거나 조사된 작업을 구현해야 하는 경우	코드, 테스트, `task.md` 상태, Git 커밋
`cc-review`	복잡한 계획, 조사, 차이점 (diffs), 또는 복잡성 핫스팟 (complexity hotspots)에 대해 구현 또는 검증 전 선택적인 심층 검토가 필요한 경우	`task.md` 내의 계획 결과; 응답 내의 구현 결과 및 수정 옵션
`cc-pr-review`	원격 PR을 반영하기 전, 관련이 있는 경우 PR 범위의 복잡성 핫스팟 검토를 포함하여 독립적인 검토 세션이 필요한 경우	PR 검토 패킷, 결과, 그리고 반영 판정 (landing verdict)
`cc-pr-land`

유지보수 기술이 패키지에 포함되어 있습니다:

cc-spec-init
: devflow/specs/ 하위에 지속 가능한 역량 명세 (capability specs)를 초기화하고 유지 관리함

cc-simplify
: 재사용성, 품질, 효율성 및 명세 드리프트 (spec drift)를 위해 변경된 코드를 검토함

cc-roadmap은 이제 경로를 권장하기 전에 계획 상태 (planning posture), 증거 성숙도 (evidence maturity), 표준 프로젝트 언어 (canonical project language), 그리고 지속 가능한 결정 맥락 (durable decision context)을 기록합니다. 이를 통해 아이디어 단계, 활성 사용자, 유료 고객, 인프라, 그리고 복구 작업이 동일한 질문을 강제로 거치지 않도록 하며, 로드맵 항목이 제2의 어휘를 만들어내는 것을 방지합니다. 개발자 대상 또는 운영자 대상 로드맵 항목 또한 타겟 사용자, 첫 가치 창출 시간 (time to first value), 매직 모먼트 (magic moment), 채택 병목 현상 (adoption bottleneck), 그리고 도메인 핸드오프 (domain handoff) 정보를 cc-plan으로 전달합니다.

표준 언어 (Canonical language)와 지속 가능한 결정들은 cc-devflow 네이티브 소스 내에 유지됩니다: devflow/specs/, devflow/roadmap.json, devflow/ROADMAP.md, task.md, Git 히스토리, 그리고 PR 진실 (truth). 레거시 계획 산출물 (Legacy planning artifacts)은 읽기 가능한 폴백 입력 (fallback inputs)으로만 사용됩니다.

cc-plan은 cc-do가 시작되기 전에 더 많은 구현 결정들을 동결 (freeze)합니다. 사소하지 않은 계획은 최소 기능 (minimal viable) 및 이상적인 아키텍처 옵션을 비교하며, 전체 설계에는 결정 지평 (decision horizon)과 오류/구조 (error/rescue) 매핑이 포함됩니다. 테스트 우선 (test-first) 계획은 테스트 프레임워크 증거, 공개 테스트 심 (public test seams), 명세 스타일의 테스트 이름, 공개 검증 경로, 동작 단언 (behavior assertions), 모의 객체 경계 (mock boundaries), 커버리지 품질, 필수 회귀 테스트 (mandatory regression tests), 인터페이스 깊이, Green minimality 가드, 리팩터링 후보, 그리고 기존 동작이 변경될 때의 수직적 트레이서 불릿 슬라이스 (vertical tracer-bullet slices)를 기록합니다. 핸드오프 전에, cc-plan과 cc-investigate

또한 소스 로드맵 항목을 조정하여 RM 상태, REQ/FIX 바인딩 (binding), 진행 상황 및 사양 진단 (spec diagnosis)이 동결된 변경 아티팩트 (change artifacts)로부터 벗어나지 않도록 합니다.

모든 배포된 스킬 (skill)은 자체적인 references/checklist-contract.md를 가집니다.

공유된 체크리스트 참조는 존재하지 않습니다. 체크리스트는 해당 스킬만을 위한 일시 정지 지점 계약 (pause-point contract)이며, 그 증거는 task.md, 응답, PR 진실 (PR truth), Git 히스토리, 또는 릴리스 검증 (release verification)과 같은 해당 스킬의 일반적인 증거 저장소 (evidence sink)에 기록되어야 합니다.

모든 계획 후 단계 (post-planning stage)는 task.md, 현재 Git 히스토리/상태, 그리고 존재하는 경우 PR 또는 핸드오프 진실 (handoff truth)로부터 시작됩니다. 런타임 컨텍스트 쿼리 계층 (runtime context query layer)은 존재하지 않으며, 논란이 되는 사실은 소스 아티팩트에서 다시 읽어야 합니다. 공개적인 스킬 엔트리포인트 (skill entrypoints)를 가볍게 유지하려면 npm run benchmark:skills를 사용하십시오. 더 깊은 계획 규칙은 기본 컨텍스트 대신 조건부 참조 (conditional references) 뒤에 위치해야 합니다.

cc-review는 선택 사항이며 cc-check보다 더 심층적입니다. 이는 동결된 계획 또는 근본 원인 계약 (root-cause contract)을 검토하기 위해 cc-plan / cc-investigate 직후에 실행되거나, 구현을 검토하기 위해 cc-do 이후에 실행될 수 있습니다. 또한 중첩된 스캔 (nested scans), 반복적인 멤버십 확인 (membership checks), 렌더링 재계산 (render recomputation), 그리고 N+1 데이터베이스/API 패턴을 위한 내장된 복잡성 핫스팟 측면 (complexity hotspot facet)을 포함합니다. 사소하지 않은 검토 결과는 증거, 진단, 현상적/필수적/철학적 인지 계층 (Phenomenal/Essential/Philosophical cognitive layers), 인과 경로 (causal path), 최소 3개의 상위 계층 (upstream layers), 그리고 최소 3개의 하위 계층 (downstream layers)을 기록합니다. 계획 및 조사 검토 결과는 task.md에 직접 작성됩니다. 구현 검토 결과는 수정 옵션과 함께 응답으로 반환되며, 사용자는 코드가 수정되기 전에 수정 경로를 선택합니다. PR 검토는 응답 또는 GitHub 검토에 유지됩니다. 로컬 검토 보고서, 원장 (ledger), 결과 JSON, 또는 기타 검토 출력 파일은 작성되지 않습니다.

cc-check

cc-check는 이제 QA를 단순히 테스트 통과 여부(green-test)의 문제가 아닌, 피드백 루프 (feedback-loop) 문제로 다룹니다. 버그 수정 (Bugfix) 및 동작 (behavior) 작업은 현실을 증명하기 위해 사용된 루프, 기대 동작 대비 실제 동작 (expected versus actual behavior), 재현 단계 (reproduction steps), 테스트 경계 품질 (test boundary quality), 그리고 깨끗한 공개 테스트 심 (public test seam)이 존재하지 않을 때의 아키텍처 후속 조치 (architecture follow-ups)를 기록합니다. 또한, 종료 전 task.md#Failure Ledger 항목을 확인된 교훈 (confirmed lessons), 노이즈 (noise), 또는 미해결 리스크 (unresolved risks)로 분류합니다.

cc-act는 필요한 경우 해당 증거를 PR 브리프 (PR briefs), 인수인계 (handoffs), 또는 장애 사후 분석 (incident postmortems)으로 전달합니다. 이는 확인된 실패 원장 (Failure Ledger) 항목을 사후 분석 (postmortems)으로 압축하며, 각 장애에 대해 워크플로 패치 후보 (workflow patch candidate)를 명시하거나 명확한 '조치 없음 (no-action)' 결정을 내릴 것을 요구합니다. 종료 시 소스 로드맵 (source roadmap) 진행 상황을 확인하고, devflow/roadmap.json을 업데이트하며, 검증된 현실이 변경될 때 devflow/ROADMAP.md / devflow/BACKLOG.md를 재생성합니다. 후속 조치 (Follow-ups)는 로드맵이나 백로그 (backlog)에 다시 기록되기 전에 현재 동작, 원하는 동작, 주요 인터페이스 (key interfaces), 수락 기준 (acceptance criteria), 그리고 명시적인 범위 외 (out-of-scope) 노트를 포함한 내구성 있는 동작 브리프 (durable behavior briefs)여야 합니다.

전체 .claude 스킬 팩 (skill pack)을 사용하려면 다음을 실행하세요:

npx cc-devflow@latest init --dir /path/to/your/project
npx cc-devflow@latest init --dir /path/to/your/project --force

--force는 cc-devflow가 관리하는 분산 스킬 (distributed skills)만 업그레이드하며, .claude 하위의 관련 없는 프로젝트 파일은 보존합니다.

이 리포지토리를 로컬에서 개발할 때:

node bin/cc-devflow-cli.js --help
node bin/cc-devflow-cli.js init --dir /tmp/example-project
node bin/cc-devflow-cli.js adapt --cwd /tmp/example-project --platform codex

skills.sh는 단일 스킬 배포 채널로 지원됩니다:

npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
npx skills add https://github.com/Dimon94/cc-devflow --skill cc-next
npx skills add https://github.com/Dimon94/cc-devflow --skill cc-dev
...

전체 팩에는 cc-devflow init을, 생성된 플랫폼 출력물에는 cc-devflow adapt를, 그리고 skills add를 사용하세요.

한 번에 하나의 스킬(skill)만 사용하고 싶을 때만 해당합니다.

CC-DevFlow는 내구성이 있는 워크플로(workflow) 문서가 작성되기 전에 계층화된 YAML 설정(config)을 읽습니다:

~/.cc-devflow/config.yml
<repo>/.cc-devflow/config.yml
<repo>/.cc-devflow/config.local.yml

우선순위는 결정론적(deterministic)입니다: 기본값(defaults) < 사용자(user) < 프로젝트(project) < 로컬(local) < 환경(environment) < CLI.

output.document_language는 머신에 의해 강제되며, 현재 en 및 zh-CN을 지원합니다. 이는 내구성이 있는 계획(planning), 검토(review), 핸드오프(handoff)의 Markdown 헤딩(headings), 산문(prose), 플레이스홀더(placeholders), 증거 요약(evidence summaries), 그리고 PR/본문 초안(PR/body drafts)을 제어합니다. 코드, 명령(commands), 경로(paths), 스키마 키(schema keys), API 이름, 그리고 커밋 타입/스코프 리터럴(commit type/scope literals)은 변경되지 않은 상태로 유지됩니다. 비표준 선호 사항은 agent_preferences 아래에 속하며, 이는 스타일을 안내하지만 워크플로 계약(workflow contracts)을 무시하지는 않습니다.

version: 1
output:
  document_language: en
...

유용한 명령(commands):

npx cc-devflow config init --cwd /path/to/your/project --project
npx cc-devflow config set output.document_language zh-CN --cwd /path/to/your/project --project
npx cc-devflow config resolve --cwd /path/to/your/project --format policy
...

전체 샘플은 config/user-config.template.yml을 참조하세요.

분산된 스킬(Distributed skills)은 .claude/skills/에 위치합니다:

.claude/skills/<skill>/
├── SKILL.md
├── PLAYBOOK.md
...

배포된 각 스킬은 런타임 계약(runtime contract)을 로컬에 유지합니다:

SKILL.md는 YAML 프론트매터(frontmatter)와 Harness Contract를 포함합니다.
PLAYBOOK.md는 Visible State Machine을 포함합니다.
로컬 리소스는 이를 소유한 스킬 옆에 유지됩니다.

현재 배포된 스킬 폴더는 다음과 같습니다:

.claude/skills/cc-roadmap/
.claude/skills/cc-next/
.claude/skills/cc-dev/
.claude/skills/cc-plan/
.claude/skills/cc-investigate/
.claude/skills/cc-do/
.claude/skills/cc-review/
.claude/skills/cc-pr-review/
.claude/skills/cc-pr-land/
.claude/skills/cc-check/
.claude/skills/cc-act/
.claude/skills/cc-spec-init/
.claude/skills/cc-simplify/

devflow/specs/는 내구성이 있는 역량의 진실(capability truth)인 INDEX.md와 capabilities/*.md를 저장합니다.

.- 새로운 변경 디렉터리는 요구사항의 경우 REQ-<number>-<description>, 버그 수정의 경우 FIX-<number>-<description>를 사용합니다. REQ와 FIX 번호는 독립적으로 증가하므로, 동일한 번호가 두 접두사 모두에 존재할 수 있습니다. 병렬 워크트리 (worktrees) 또한 중복된 번호를 생성할 수 있으므로, 전체 변경 키 (change key)는 작업을 구분하기 위해 반드시 구체적인 설명을 포함해야 합니다. devflow/changes/<change>/는 task.md, 선택 사항인 handoff/pr-brief.md, 그리고 Git 커밋에 내구성이 있는 변경 진실 (change truth)을 저장합니다. 실제 실패는 task.md#Failure Ledger에서 시작됩니다. 확인된 반복적 교훈은 devflow/postmortems/ 아래의 인시던트 사후 분석 (incident postmortems)으로 압축될 수 있습니다.

.- 새로운 변경 사항은 기본적으로 사람이 작성한 하나의 마크다운 (Markdown) 아티팩트인 task.md를 생성합니다. 기능 계획 (Feature plans)은 동결된 설계를 ## Contract Summary에 기록하며, 버그 조사 (bug investigations)는 근본 원인에 대한 진실을 ## Root Cause Contract에 기록합니다.

Dimon94/cc-devflow

요약

핵심 포인트

댓글