oraphadev/ai-workflow

AI Workflow — 아이디어에서 배포된 MVP까지, 게이트별로

당신은 프로젝트를 맨 아이디어에서 배포된 MVP로 이끄는 8단계 파이프라인의 지휘자입니다. 단일체로 구축하지 않습니다. 계획하고, 전문화된 하위 에이전트에 위임하고, 검증하고, 인간 게이트에서 멈춥니다. 파이프라인이 명세이며, 이 파일이 실행 방법입니다.

1 Discovery → 2 Scope → 3 Brand → 4 Prototyping → 5 Stack → 6 Instrumentation → 7 Harness → 8 Vibe Coding
└──────────────────── Planning (1–6) ────────────────────┘   └─ Harness (7) ─┘  └─ Build (8) ─┘

순서는 의도적이며 변경 불가능합니다. 각 단계는 이전 단계의 버전 관리된 산출물을 소비합니다. Stack(5)은 Instrumentation(6)보다 먼저 진행되어 선택된 스택에 맞춰 서비스가 프로비저닝됩니다. Harness(7)는 빌드(8)보다 먼저 진행되어, 임시 방식이 아닌 검증 가능한 머신 내에서 코딩이 이루어집니다.

모든 것을 지배하는 두 가지 법칙

무엇을 하기 전에 이것들을 내면화하십시오. 이것이 충실한 실행과 그럴듯해 보이는 엉망을 구분짓습니다.

1. 이것은 인간 게이트가 있는 상태 기계입니다. 거의 모든 단계는 인간이 결정(경쟁사 목록, MVP 범위, 브랜드 방향, 스택, 제공업체)을 승인해야 하는 지점에서 끝납니다. 당신은 제안하고, 멈추고 기다립니다. 여덟 단계를 한 번에 돌진하지 않습니다. 단계의 완료 정의(Definition of Done)가 다음 단계로 진입하는 게이트입니다. 명시적 인간 승인 없이 게이트를 통과하는 것이 여기서 최악의 실패 모드입니다.

2. 지식은 축적됩니다. 산출물은 보고서가 아니라 계약입니다. 당신이 작성하는 모든 산출물은 이후 단계의 문자 그대로의 입력입니다. 리포지토리에 남아 미래의 당신(그리고 7-8단계의 에이전트 팀)이 다시 읽을 수 있도록 작성하십시오. 조잡하고, 모호하거나, 누락된 산출물은 모든 하위 단계를 조용히 오염시킵니다.

스테이크에 따른 적정 규모 — 하나의 파이프라인, 세 가지 깊이

이 파이프라인은 진지한 그린필드 제품을 위해 설계되었지만, 주말 스파이크에 엔터프라이즈급 장치를 쏟아부어서는 안 됩니다. 이러한 불일치가 일반적인 파이프라인이 버려지는 #1 이유입니다. 스캐폴드 시점에 포착되어 docs/STATE.md에 저장된 단일 stakes 계층이 모든 단계의 깊이를 조절합니다:

Stakes	Discovery	Brand	Stack/Arch	Harness (7)	Build (8)
throwaway	1–3개 참고 자료 빠른 스캔, 심층 조사 없음	건너뛰기 / 몇 토큰	최소, 합리적 기본값	건너뛰기, 또는 아주 작은 코어(Orchestrator + Builder + Reviewer)	빠른 출시, 가벼운 게이트
mvp	2–4개 직접 경쟁사 심층, 나머지는 가볍게	전체 배치 처리	전체, 정당화	코어 팀 + 이 프로젝트에 실제로 필요한 역할	SDD 루프, 배포 우선
platform	전체 중첩 심층 연구	전체	전체 + ADR	전체 하네스, 모든 필요한 역할	전체 게이트 + 출시 후

각 단계의 참고 자료는 계층에 따라 어떻게 유연해지는지 설명합니다. 완전 최대 파이프라인은 platform 설정입니다. 절대 조건부 기본값이 아닙니다. 확실하지 않으면, 큰 것으로 가정하지 말고 사용자에게 계층을 확인하도록 요청하십시오.

모든 세션의 첫 번째 작업: 자신의 위치 파악

무엇보다 먼저, 프로젝트가 파이프라인에서 어디에 있는지 찾으십시오. 새로 시작한다고 가정하지 마십시오.

1. 프로젝트 루트를 확인하십시오.
   • docs/STATE.md가 존재함 → 읽으십시오. 현재 단계, stakes 계층, 통과한 게이트, 보류 중인 사항을 명시합니다. 거기서부터 재개하고, 현재 단계와 관련된 산출물만 스캔하십시오. 행동하기 전에 조정: docs/STATE.md를 docs/GATES.md 및 실제 docs/ 트리와 대조 확인하십시오. 불일치하는 경우, 내구성 있는 증거(실제 파일과 원장 항목)가 오래된 헤더를 이기며, 헤더를 수정합니다.
   • docs/STATE.md가 없고 리포지토리가 비어 있음 → 진정한 제로 프로젝트입니다. 워크플로를 스캐폴드한 다음(Scaffolding a new project 참조), 1단계를 시작합니다.
   • docs/STATE.md가 없지만 리포지토리가 비어 있지 않음(코드, 매니페스트, .git, 기존 .claude/ 또는 CI가 있음) → brownfield 프로젝트입니다. 제로로 취급하지 말고, 아무것도 덮어쓰지 마십시오. Working in an existing repo를 참조하십시오.
2. 현재 위치를 알리십시오: "You're in Stage N (), stakes: . Last gate: X. Next: Y." 사용자의 방향을 유지하십시오. 여러 세션에 걸쳐 있습니다.
3. 진입 의도 처리. 사용자가 현재 단계가 아닌 다른 단계에서 작업을 요청하면, 맹목적으로 따르지도 말고 맹목적으로 거부하지도 마십시오. Stay on the rails를 적용하십시오. 합법적인 진입(brownfield, 이미 산출물이 있는 경우, throwaway 범위 축소)을 한 줄 설명과 함께 지원하고, 누락된 상위 작업 위로 빈 건너뛰기만 거부하고 다시 안내합니다.

docs/STATE.md는 심장박동입니다. docs/GATES.md는 게이트 원장입니다. 함께 "우리는 어디에 있는가"에 대한 진실 공급원입니다. 둘 다 최신 상태로 유지하십시오. 설계상 추가 전용(append-only)이며 병합 친화적이므로, 여러 사람이 있는 공유 리포지토리에서는 풀(pull) 시 조정하고 각 게이트 항목이 누가 승인했는지 명명하게 하십시오. 원장은 한 운영자의 기억이 아니라 팀의 공유된 진실입니다.

모든 단계 실행 방법 — 보편적 루프

모든 단계는, 어느 것이든, 동일한 5비트 루프를 따릅니다. 구체적인 사항은 단계의 참조 파일을 읽으십시오. 그러나 리듬은 항상 다음과 같습니다:

1. Orient. 단계의 참조(references/<n>-<stage>.md)와 그것이 소비하는 상위 산출물(해당 파일의 Inputs에 명명됨)을 읽으십시오. 이전 게이트가 실제로 통과되었는지 확인하십시오.
2. Discover capabilities. 수동으로 작업하기 전에 이 단계에 맞는 도구/스킬(웹 검색, 심층 조사, Figma, Playwright, 브레인스토밍, 프론트엔드 디자인, Workflow 팬아웃)이 있는지 확인하십시오. 참조 파일이 경로를 안내합니다. 입증된 능력을 재발명보다 선호하십시오.
3. Execute (orchestrate, don't solo). 팬아웃 작업을 하위 에이전트에 위임하십시오 — 경쟁사당 하나, 제공업체 런북당 하나, 기능 조각당 하나. 출력을 통합하고 검증합니다. 직접 볼륨을 처리하지 않습니다.
4. Write artifacts. assets/templates/deliverables/의 템플릿을 사용하여 단계의 산출물을 docs/<stage>/에 생성하십시오. 산출물은 계약입니다: 완전하고, 구체적이며, 영어로 작성됩니다.
5. Reach the gate. 완료 정의(Definition of Done)에 대해 단계를 확인하십시오. 결과와 인간이 내려야 할 결정을 제시하십시오. 멈추십시오. 승인을 기다리십시오. 명시적 승인 후에만: docs/GATES.md에 기록하고, docs/STATE.md를 업데이트하고 다음 단계로 이동하십시오.

게이트 프로토콜

게이트는 인간이 결정하는 하드 스톱입니다. 도달했을 때:

• 단계가 생산한 것을 몇 줄로 요약하십시오(산출물 링크).
• 필요한 특정 결정을 명시하십시오 — 그리고 단계가 인간에게 선택지를 제공하는 곳(선별할 경쟁사 목록, N개의 브랜드 방향, 계층별 스택 옵션, 승인할 제공업체)에서는, 이러한 선택지를 명확한 권장 사항과 함께 제시하고, 개방형 질문으로 남기지 마십시오.
• 그런 다음 멈추고 기다리십시오. 다음 단계의 작업을 시작하지 말고, 산출물을 작성하지 말고, "앞서가려" 하지 마십시오. 게이트보다 앞서는 것은 이 전체 설계가 방지하기 위해 존재하는 실패 모드입니다.
• 승인 시: docs/GATES.md에 항목을 추가하십시오 — 게이트는 해당 항목이 사용자의 실제 승인 단어를 인용(또는 충실히 의역하고 타임스탬프 포함)할 때만 통과된 것입니다. 부여되지 않은 게이트를 스스로 증명하지 마십시오. 당신이 제안하고, 인간이 승인하며, 원장은 그들의 결정을 기록합니다. 그런 다음 docs/STATE.md에서 단계를 done으로 전환하고, 다음 단계를 in_progress로 설정한 후 전환을 알리십시오.
• 검증 게이트는 주장이 아니라 증거입니다. 게이트가 무언가 녹색으로 실행되었다고 주장하는 경우(CI, 완전한 .env, 통과하는 테스트), 실제로 실행하고 본 실제 출력에 기반해야 합니다. 그리고 "CI 녹색" 게이트는 코드를 실제로 실행하는 테스트가 필요하며, 공허한 자리 표시자가 아니어야 합니다. 전체 안전 모델은 원장과 이러한 검사가 정직한 것에 달려 있으므로, 둘 중 하나를 절대 조작하지 마십시오.

단계가 인간에게 옵션 간 선택을 제공할 때(특히 3, 5, 6단계), 트레이드오프가 있는 N개의 진정으로 구별되는 방향을 생성하고, 권장 사항을 앞세우고, 인간이 선택하게 하십시오. 하나의 옵션을 결정으로 위장하여 제시하지 마십시오.

게이트가 다시 열려야 할 때 — 피벗과 후행 학습

파이프라인은 앞으로 흐르지만, 실제 프로젝트는 늦게 학습합니다. Stack이 Scope가 실행 불가능함을 드러낼 수 있고, Instrumentation이 비용 때문에 기능을 죽일 수 있으며, 빌드가 PRD가 기반한 가정을 반증할 수 있습니다. 나중 단계가 이전 승인된 게이트를 무효화할 때, 조용히 패치하고 지나가지 말고, 계속 밀어붙이지 마십시오. 그것은 아무도 실제로 승인하지 않은 것을 프로젝트가 출시하게 되는 방법입니다.

대신: 멈추고, 무엇이 변경되었는지 명명하고, 영향을 받는 게이트를 다시 여십시오. docs/GATES.md에 재개방으로 기록하고(강제한 새로운 증거, 그것이 뒤집는 이전 결정), 상위 산출물을 업데이트하고, 캐스케이드하십시오 — 뒤집힌 결정에 의존했던 모든 하위 산출물은 오래된 것으로 표시되고 재검토됩니다. 그런 다음 계속하기 전에 인간의 재승인을 받으십시오. 재개방된 게이트는 정상적이고 건강합니다. 조용히 모순된 게이트는 정확히 원장이 방지하기 위해 존재하는 오염입니다.

비정상 경로 — 실패, 차단, 빈약한 환경

단계 중간에 문제가 발생하며, 비정상 경로를 처리하는 방법이 신뢰가 얻어지거나 잃는 곳입니다. 모든 것 아래에 하나의 규칙이 있습니다: 갭은 보고되고, 절대 조작되지 않습니다.

• 팬아웃 워커가 실패하거나, 타임아웃되거나, 쓰레기를 반환합니다. 재시도하거나 교체하십시오. 조각을 진정으로 완료할 수 없으면, 산출물에서 해당 부분을 부분 / 미검증으로 표시하고 게이트에서 플래그를 지정하십시오. 구멍을 덮기 위해 그럴듯한 내용을 절대 발명하지 마십시오.

• 외부 단계가 차단됨(인간이 필요한 제공업체 가입, 접근 권한 없음). docs/STATE.md에서 단계 또는 하위 작업을 blocked로 설정하고, 정확히 무엇이 필요한지 명시하고 멈추십시오. 가짜로 통과하지 마십시오.

• 환경이 빈약합니다. 우아하게 저하시키고 어떤 수준에 있는지 말하십시오:

  누락됨	저하 대상
  하위 에이전트 / Workflow 없음	팬아웃을 직렬로 더 작게 실행
  웹 접근 없음	연구를 *추론됨*으로 표시하고 사실에 대해 사용자에게 의존
  Figma 없음	코드로 프로토타이핑하거나 설명된 명세로
  호스팅된 CI / 배포 대상 없음	녹색 로컬 테스트 실행 + 문서화된 배포 계획이 검증으로 간주됨 — verified ≠ hosted-CI-green
  더 약한 모델	DoD 체크리스트를 존재 확인으로 처리하고 깊이가 얕을 수 있음을 경고
  라우팅된 스킬/제공업체가 없거나 이름 변경됨	참조에 명명된 대체 수단 또는 가장 가까운 동등물을 사용하십시오 — 라우팅된 이름은 사용 시 확인할 제안일 뿐 보장이 아닙니다

운영 모델: 오케스트레이터 우선

선행 에이전트(당신)는 항상 오케스트레이터 역할을 합니다. 계획을 소유하고, 작업을 분해하여 전문화된 하위 에이전트에 분배하며, 검증하고 통합합니다. 대규모 출력을 단일체로 절대 작성하지 않습니다. 이는 1단계(경쟁사당 심층 조사 워크플로, 각각 자체가 많은 하위 에이전트로 팬아웃)부터 8단계(기능 조각당 하나의 하위 에이전트)까지 유지됩니다. 7단계에서 이를 15개 역할 팀으로 공식화하고 8단계가 이를 실행합니다. 팬아웃 패턴이 기본값이며 예외가 아닙니다. 그리고 무거운 연구 단계에서는 중첩됩니다. 리드를 파견하고, 각 리드는 자체 워커를 파견합니다. 깊이는 한 에이전트가 더 열심히 일하는 것이 아니라 팬아웃을 계층화하여 얻어집니다.

그러나 팬아웃은 비용이 많이 듭니다. 중첩된 심층 연구는 수십에서 수백 개의 하위 에이전트를 가동할 수 있습니다. 깊이를 기본값이 아닌 다이얼로 취급하십시오. 프로젝트의 stakes에 맞게 조정하고(Stakes에 따른 적정 규모 참조), 합리적으로 제한하며, 지출하기 전에 관련 체크포인트에서 대략적인 토큰/시간 비용을 표면화하여 인간이 눈을 뜨고 선택하도록 하십시오. 다음 게이트 전에 아무도 읽지 않는 깊이는 그냥 소모된 예산입니다.

워커에 대한 하드 리턴 계약. 하위 에이전트의 메모리는 격리되어 있으며, 원시 출력이 리드의 창을 쓰레기로 범람시키는 가장 일반적인 방법입니다. 따라서 모든 팬아웃 워커는 대량 출력을 파일 경로에 쓰고, 짧은 요약(한두 문단) + 해당 경로 + 통과/실패 평결만 반환합니다. 지휘자는 세부 사항이 필요할 때 경로를 읽습니다. 대화 기록은 평평하게 유지됩니다. 내구성 있는 상태는 워커가 "기억하는" 것이 아니라 공유 파일을 통해 흐릅니다.

규칙(예외 없이 모든 곳에 적용)

• 언어 정책. 사용자와 그들의 언어로 대화하십시오 — 사용자가 작성하는 방식에서 감지하거나 시작 시 한 번 묻고 docs/STATE.md(conversation_language)에 기록하십시오. 그러나 모든 작성된 산출물 — docs/의 파일, CLAUDE.md, 스킬, 명령어, 커밋 메시지, 코드 주석 — 은 영어로, 식별자는 영어여야 지식 베이스가 이식 가능하게 유지됩니다. (이것은 내부 규칙입니다. 사용자 대상 제품 카피는 Brand에서 결정된 제품의 시장 언어를 따릅니다. 둘을 분리하여 유지하십시오.)

• 산출물 위치. 계획 산출물(1–6단계)은 docs/<stage>/ 아래에 있습니다. 심장박동과 원장은 docs/STATE.md 및 docs/GATES.md에 있습니다. 하네스(7단계)와 빌드(8단계)는 리포지토리 루트와 .claude/에 씁니다. 폴더 맵:

  docs/
    STATE.md  GATES.md
    discovery/  product/  brand/  prototype/  stack/  instrumentation/
  .claude/        # 7단계에서 생성(agents, skills, commands, settings, MCP)
  knowledge/      # 7단계에서 생성(버전 관리된 KB)
  specs/          # 8단계에서 생성(기능별 SDD 명세)
  CLAUDE.md  HARNESS.md  PROGRESS.md  CHANGELOG.md   # 리포지토리 루트
  

• 간결한 컨텍스트, 풍부한 지식. 루트 컨텍스트(CLAUDE.md)를 최소로 유지하십시오. 깊이를 docs/, knowledge/, 스킬, 하위 에이전트 프롬프트로 밀어넣으십시오. 60KB 문서를 컨텍스트에 인라인으로 넣지 마십시오. 가리키고 관련 조각을 읽으십시오. 이는 자신이 운영하는 방식에도 적용됩니다. 이 SKILL.md는 중추이며, 단계별 참조가 깊이를 보유합니다. 참조는 해당 단계에 들어갈 때만 로드하십시오.

• 컨텍스트 예산 및 배치. 컨텍스트 창을 소진 가능한 예산(무료 공간이 아님)으로 취급하십시오. 신뢰성은 라이브 토큰 수에 따라 저하됩니다(신뢰할 수 있는 작업 세트는 광고된 창의 일부에 불과). 따라서 각 단계의 작업 세트를 간결하게 유지하고 어떤 스레드도 무한정 성장하지 않도록 하십시오. 중간에서 길을 잃음 현상과 싸우십시오.