kickoff AGENTS.md

kickoff — 프로젝트 시작 워크플로 (spec → plan → design)

새 프로젝트/기능을 시작할 때 따르는 3단계 절차를 정의한다. 모든 AI 코딩 에이전트가 읽을 수 있는 도구 중립 지침이다. (Claude Code는 추가로 SKILL.md를 통해 /kickoff 슬래시 명령으로도 이 절차를 부른다.)

요구사항 정리 → ① documents/spec.md → ② documents/plan.md → ③ documents/design.md → (디자인 AI가 화면 제작)

세 문서는 프로젝트 루트의 documents/ 폴더에 모아 둔다. 폴더가 없으면 첫 문서를 쓸 때 만든다.

언제 적용하나: 사용자가 새 프로젝트를 시작하거나, "프로젝트 시작하자 / spec 만들자 / plan 짜자 / MVP 단위로 계획 / 디자인 문서 만들어" 같이 요청하거나, 만들 것의 목표·요구사항을 설명하며 구체화를 부탁할 때. 기존 plan.md 갱신(MVP 체크, 진행 기록 append)에도 쓴다.

이건 단순 문서 생성기가 아니다. 핵심은 각 단계의 일하는 방식이다 — spec은 쓰기 전에 검토 대화부터, plan은 검증 가능한 MVP 슬라이스, design은 디자인 AI에게 넘길 깨끗한 입력. 이 방식이 곧 워크플로의 본질이라, 형식보다 이걸 지키는 게 중요하다.

대화는 한국어로. 생성하는 문서는 한글 본문 + 영어 라벨/경로/코드 혼용.

---

작동 방식 — 상태를 보고 단계를 정한다

0. 먼저 프로젝트 디렉토리를 확정한다 (스캔보다 먼저)

이건 프로젝트 시작 절차라, 첫 호출 때 작업 위치가 모호한 경우가 흔하다. 무엇이든 감지·생성하기 전에 프로젝트 루트부터 확정해라:

• 새 프로젝트: 폴더가 아직 없으면 이름을 정하고 만든다(또는 만들 위치를 사용자와 확인). 이후 모든 문서는 그 폴더에 쓴다.
• 현재 위치가 컨테이너면 주의: 사용자가 수십 개 프로젝트를 담는 상위 폴더에 있을 수 있다. 그곳을 프로젝트 루트로 착각하면 다른 프로젝트의 SPEC.md를 잘못 매칭해 단계를 오판하거나 헛된 "이미 있는데?" 확인을 띄운다. 한 폴더에 여러 프로젝트가 섞여 보이면, 어느 폴더가 이번 프로젝트인지 확인하고 거기로 좁힌다.
• 스캔 범위는 확정된 프로젝트 루트 안으로 한정. 상위로 거슬러 올라가지 말고, 옆 프로젝트로 새지 마라.
• 루트를 확정했으면 문서 위치는 그 안의 documents/ 다. 없으면 만든다(첫 문서를 쓸 때 같이 만들면 된다).

그다음 — 단계 판단 (명시적 캐스케이드)

확정된 프로젝트 루트를 보고 다음에 할 단계를 정한다. 겹치지 않게 위에서부터 순서대로 판단한다:

1. spec 없음 → STAGE 1 (spec)
2. spec 있음 + plan 없음 → STAGE 2 (plan)
3. spec 있음 + plan 있음 + design 없음 → STAGE 3 (design)
4. 셋 다 있음 → 생성할 게 없다. 현재 상태를 요약하고, 살아있는 plan.md 동기화(체크/진행기록 갱신)를 제안한다.

사용자가 특정 단계를 지정하면(예: "plan 짜자", /kickoff design) 그 단계로 바로 간다. design은 spec에만 의존한다 — plan이 없어도 spec만 있으면 design을 만들 수 있다. design을 plan 뒤로 막지 마라.

캐노니컬 파일과 변형 감지 (덮어쓰기 사고 방지)

새로 만들 때의 표준 파일명·위치는 프로젝트 루트 아래 documents/ 폴더의 spec.md, plan.md, design.md(화면 묶음이 여럿이면 surface별 복수 허용: design-app.md, design-landing.md).

단, 감지는 정확매칭으로 하지 마라. 기존 프로젝트는 파일명도 위치도 제각각이다 — SPEC.md, CMS_Spec.md, TechSpec.md, DESIGN_BRIEF.md, landing-brief.md 등. 단계를 정하기 전에 프로젝트 루트 + documents/ + docs/ 에서 대소문자 무시 + 부분 매칭으로 이미 존재하는 파일을 먼저 찾아라: