Feature Add

---
name: feature-add
description: 완료된 프로젝트(docs/PRD.md·plan_setup·harness_setup·loop_setup/LOOP.md 가 있고 루프가 도는 중이 아닌 상태)에 기능을 더한다. "xx 기능 추가하려는데" 로 시작하는 요청을 받아, 요청이 모호하면 idea-brainstorm 부터, 명확하면 prd-generator 부터 필요한 기존 스킬(idea-brainstorm → prd-generator → trd-generator(기술 결정이 새로 생기거나 바뀔 때만) → architecture-generator → plan-generator)을 순서대로 부르되 각 문서를 처음부터 다시 쓰지 않고 후미에 "## 추가 N: <기능>" 절만 붙이게 하고(N 은 요청 단위의 공통 번호, FR·US·TD·설계 단위 번호는 이어짐, 기존 항목의 변경은 "FR-003 수용 기준 2 를 다음으로 대체"), plan_setup/ 에 phase-NN-<기능이름> 을 끝번호로 더한 뒤 harness-update(새 흐름·커버 영역)·loop-update(DAG)를 부른다. 사용자가 "댓글 기능 추가하려는데", "알림 넣고 싶어", "이제 권한 관리도 붙이자", "MVP 에 이 기능 더하자", "다음 버전에 뭐 넣을지 정하자", "이 앱에 xx 도 되게 해줘", "기능 확장하자", "로그인을 비밀번호 방식으로 바꾸자" 처럼 완료된 프로젝트의 요구를 늘리거나 바꾸려 할 때 반드시 이 스킬을 사용한다. 코드부터 고치거나 PRD 를 새로 쓰기 시작하지 말고 이 스킬로 먼저 후미 절과 phase 를 만든다. 동작을 그대로 두고 모양만 바꾸는 것은 refactor-plan, 안 되는 것을 고치는 것은 bug-fix, docs/PRD.md 가 없으면 code-to-docs 가 먼저다. 루프가 도는 중(STATE.md 에 in_progress phase)에는 진입하지 않는다.
---

# 기능 추가 (Layer 6 · MVP → 실제 제품)

## 이 스킬의 목적

프로젝트가 완료되면 MVP 를 실제 제품으로 키우는 요청이 온다 — "댓글 기능 추가하려는데", "알림 같은 걸 넣고 싶은데". Layer 0~5 의 스킬은 전부 "처음 만드는 것" 을 전제로 쓰여 있어
그대로 부르면 PRD 를 처음부터 다시 쓰고 phase 번호가 흔들린다. 이 스킬은 **어느 스킬을 어떤 모드로 부르는가만 정하는 라우터**다 — 각 문서의 형식·추적표·버전은 그 문서의 스킬 규칙이고, 이 스킬은 호출 지시만 넘긴다.

이 스킬은 코드를 고치지 않고 문서를 직접 쓰지도 않는다. **요청을 판정하고, N 을 배정하고, 필요한 스킬을 후미 절 모드로 순서대로 부르고, phase 하나를 더한다.** 만드는 것은 개발 루프다.

```
요청을 판정한다  (모호 / 명확 — 그리고 리팩토링·버그가 섞였는가)                ← 이 스킬이 직접
   → 추가 N 배정, 기존 문서에서 마지막 번호와 "이미 있는 것" 을 읽는다              ← 이 스킬이 직접
   → docs/IDEA.md 후미 "## 추가 N"          (모호할 때만)                        ← idea-brainstorm 후미 절 모드
   → docs/PRD.md 후미 "## 추가 N" + 9절 행   (항상)                              ← prd-generator 후미 절 모드
   → docs/TRD.md 후미 "## 추가 N"           (새 TD 또는 TD 대체가 있을 때만)      ← trd-generator 후미 절 모드
   → docs/ARCHITECTURE/ 후미 "## 추가 N"    (새 설계 단위)                       ← architecture-generator 9단계
   → plan_setup/phase-NN-<기능이름>          (끝번호 phase)                       ← plan-generator 10단계
   → harness-update · loop-update                                                ← 새 흐름·커버 영역, DAG
   → 개발 루프 실행                                                              ← 사용자
```

**왜 후미 절인가.** 이 플러그인의 모든 스킬은 문서를 읽고 움직이고, 완료된 태스크는 문서의 특정 절(`FR-003`, `backend.md §3.2`)을 가리킨다. 기존 절을 고치면 통과 기록이 낡은 기준을 가리키고,
문서를 통째로 다시 쓰면 번호가 흔들리고 전체를 다시 읽어야 한다. 후미 절은 **델타**다 — 뒤 스킬은 그 절만 읽으면 이번 요청이 무엇을 바꾸는지 안다. **같은 문서 안에서는 뒤 절이 앞 절을 이긴다.**

### 여기서 하는 일과 하지 않는 일

| 하지 않는 것 | 어디서 하는가 |
|---|---|
| 코드를 고치는 것 | 개발 루프(`LOOP.md`)가 phase-NN 의 태스크로 만든다 |
| 요구사항·기술 결정·설계 단위·태스크의 형식과 절차를 정하는 것 | `idea-brainstorm`·`prd-generator`·`trd-generator`·`architecture-generator`·`plan-generator`. 이 스킬은 **부를 때 넘길 지시**만 정한다 |
| 기존 절의 본문을 고치는 것 | 하지 않는다. 바뀌는 것은 후미 절에 "FR-003 수용 기준 2 를 다음으로 대체" 로 적는다. 예외는 부른 스킬 자체의 규칙(추적표의 행 추가·값 갱신, 버전 줄, architecture-generator 9단계의 "폐기 — 대체" 표시) |
| 동작을 그대로 두고 모양만 바꾸는 것 — "중복 없애자", "라이브러리 올리자" | `refactor-plan`. PRD 수용 기준이 안 바뀌면 기능 추가가 아니다 |
| 안 되는 것을 고치는 것 — "필터가 빈 배열 나와" | `bug-fix`. 문서에 적힌 대로 동작하지 않는 것은 요구 변경이 아니다 |
| 문서 없는 코드에 기능을 더하는 것 | `code-to-docs` 가 먼저다 — 후미 절을 붙일 문서가 없고, 무엇이 "이미 있는 것" 인지 모른다 |
| 게이트 흐름을 더하고 DAG 를 다시 그리는 것 | `harness-update`·`loop-update`. 끝에 부른다 |

### 기능 추가와 리팩토링·버그의 경계

경계가 흐리면 기능 phase 에 리팩토링이 섞여 "무엇을 만들었는가" 를 판정할 수용 기준이 없어지거나, 버그 수정이 phase 로 들어가 회귀 검사·BUG-NN 기록을 건너뛴다. 판정은 두 질문이다.

| 질문 | 예 | 아니오 |
|---|---|---|
| PRD 의 수용 기준이 늘거나 바뀌는가 (새 FR, 또는 기존 FR 의 기준 대체) | **기능 추가** | ↓ |
| 지금 문서에 적힌 대로 동작하지 않는가 | `bug-fix` | `refactor-plan` (동작도 문서도 그대로, 모양만) |

as-is 문서(`> 코드에서 역으로 작성`)에서는 셋째 경우가 흔하다 — 관찰대로 적힌 동작이 사실은 버그였던 것. "지금 동작이 문서에 적힌 대로" 이므로 bug-fix 가 아니라 **요구 변경(기능 추가)** 이다. 후미 절이 그 FR 의 수용 기준을 대체하고, phase-01 의 현행 고정 테스트는 그 phase 안의 태스크가 새 기준으로 바꾼다.

"추가하는 김에" 는 경계를 넘는 가장 흔한 말이다. 같은 파일을 만지더라도 동작이 안 바뀌는 정리는 떼어 `refactor-plan` 으로 보낸다 — 두 phase 가 같은 파일을 건드려도 순서만 정하면 된다.

---

## 0단계. 진입 조건

둘을 확인하고 하나라도 걸리면 멈춰 보고한다. 조용히 진행하지 않는다.

| 확인 | 걸렸을 때 |
|---|---|
| `docs/PRD.md`·`plan_setup/STATE.md`·`harness_setup/`·`loop_setup/LOOP.md` 가 있는가 | `docs/PRD.md` 가 없으면 `code-to-docs` 로 보낸다(문서 없는 코드). 일부만 없으면 무엇이 없는지 보고하고 사용자가 정한다 — "없으면 새로 만드는" 경로는 없다(뒤의 harness-update·loop-update 는 언제나 부분 갱신이다) |
| `STATE.md` 의 `Phase Overview` 에 `in_progress` 인 phase 가 없는가 | 있으면 멈춘다 — "루프가 도는 중이다. phase 완료 뒤에 다시 부르라". 문서·STATE.md·LOG.md 의 필자는 루프의 코디네이터 하나여야 한다(Layer 5). `pending` phase 는 막지 않는다 — 앞선 추가·리팩토링이 더한 phase 가 아직 안 돌았어도 이 요청의 phase 를 그 뒤에 더할 수 있다 |

게이트가 미활성이어도 막지 않는다 — 새 기능의 통과 조건은 새 수용 기준이지 "기존 게이트 통과" 가 아니다. 다만 `HARNESS.md` 1절이 전부 `미활성` 이면 그 사실을 보고에 적는다(회귀를 잡을 수단이 없는 채 phase 가 돈다).

**git 상태**를 본다. 미커밋 변경이 있으면 알린다 — 뒤 스킬들이 문서를 고치므로 그 전 상태가 커밋으로 남아 있어야 한다. 사용자가 정하기 전에는 커밋하지 않는다.

---

## 1단계. 요청을 판정한다 — 모호한가, 명확한가, 무엇이 섞였는가

### 모호 / 명확

어느 스킬부터 부를지가 여기서 정해진다. 아래 넷을 요청과 기존 문서에서 읽을 수 있으면 **명확**하고 `prd-generator` 부터 간다. 하나라도 비면 **모호**하고 `idea-brainstorm` 부터 간다.

| 읽을 수 있어야 하는 것 | 예 — 명확 | 예 — 모호 |
|---|---|---|
| **무엇**(기능의 동작 한 줄) | "할 일에 댓글을 달고 본다" | "뭔가 알림 같은 걸" |
| **누가**(PRD 2절의 사용자 유형 중 누구, 또는 새 유형) | 팀원 전부 | ? |
| **어느 흐름에서**(기존 US·화면 중 어디에 붙는가) | 할 일 상세(FR-007 의 목록 옆) | ? |
| **수용 기준을 쓸 수 있는가**(관찰 가능한 결과와 실패 경로 하나) | "빈 댓글은 400", "댓글은 작성자만 삭제" | "적당히 알려 준다" |

경계선이면 묻지 말고 **모호로 본다** — idea-brainstorm 은 역질문 몇 개로 끝나고 `IDEA.md` 후미 절이 남지만, 모호한 채 PRD 로 가면 수용 기준이 가정 위에 서고 태스크가 그 가정을 구현한다.
사용자와 대화할 수 없는 환경이면 요청에서 읽히는 대로 판정하고 물었을 질문과 가정을 기록으로 남긴다.

### 섞인 것을 떼어 낸다

요청에 리팩토링("이참에 라우터 정리도")·버그("그리고 필터 안 되는 것도")가 섞여 있으면 **하지 않고 갈 곳을 답한다** — 문장을 보고에 그대로 옮겨 `refactor-plan`·`bug-fix` 를 가리킨다. 사용자가 "그래도 같이" 라고 하면 그 결정을 기록하되 이 스킬은 기능 phase 만 만든다.

### 이미 있는 것

PRD 4절·9절을 읽어 요청한 기능이 **이미 FR 로 있는지** 본다. 있고 `구현됨 (as-is)`·`계획됨` 이면 "이미 있다 — 바꾸려는 것인가" 를 확인한다. 바꾸는 것이면 이 요청은 **기존 FR 의 수용 기준 대체**가 된다(4단계). 이 확인이 없으면 같은 기능을 두 번 만드는 태스크가 생긴다.

### 추가 N 과 기능 이름

- **N 은 요청 단위의 공통 번호다.** 이 요청이 IDEA·PRD·TRD·ARCHITECTURE 에 남기는 절은 전부 같은 N 이고, 절이 안 생기는 문서(예: TD 가 새로 생기지도 바뀌지도 않아 TRD 를 열지 않음)는 그 번호를 건너뛴다.
  문서마다 따로 세면 PRD 의 "추가 3" 과 TRD 의 "추가 2" 가 같은 요청이 되어 교차 참조가 흔들린다
- N 은 `docs/` 전체에서 `## 추가 (\d+)` 의 최댓값 + 1 이다. `## 리팩토링 N`(refactor-plan)과는 **따로 센다** — "추가 1" 이 첫 기능 추가여야 phase 문서와 LOG 에서 읽힌다
- **기능 이름은 둘** — 절 이름에 쓰는 한글(`## 추가 1: 댓글`)과 phase 파일 이름에 쓰는 영문 kebab-case(`phase-02-comments`). 파일 이름을 영문으로 두는 이유는 경로·스크립트 인자에서 인코딩 문제를 피하기 위해서다(code-to-docs 의 `phase-01-baseline` 과 같다)

---

## 2단계. 기존 문서에서 번호와 기준을 읽는다

후미 절의 번호는 전부 "기존 마지막 번호 다음" 이다. 부른 스킬이 각자 세지만, **이 스킬이 먼저 세어 지시에 넣는다** — 스킬마다 세면 TRD 가 PRD 의 OQ 번호를 모른 채 `OQ-001` 부터 다시 시작한다.

| 읽는 곳 | 얻는 것 |
|---|---|
| `docs/PRD.md` 3·4·5절 | 마지막 US·FR·NFR 번호. 4절에서 이 기능과 맞닿는 기존 FR(대체 후보) |
| **프로젝트 전체**의 미결 표 — `docs/` 뿐 아니라 `harness_setup/HARNESS.md`·`loop_setup/LOOP.md` 까지 | 마지막 OQ 번호 — 미결 번호는 레이어를 넘어 이어지고 Layer 4·5 도 미결을 만든다(PRD 가 `OQ-008`, TRD 가 `OQ-011`, LOOP.md 가 `OQ-013` 까지 썼으면 새 OQ 는 `OQ-014`). `docs/` 만 세면 루프 문서의 미결과 번호가 겹친다 |
| `docs/TRD.md` 2절·13절 | 마지막 TD 번호. 이 기능이 기존 TD(저장소·API 방식·인증)로 만들어지는지, 새 결정이 필요한지 |
| `docs/ARCHITECTURE/*.md` 3절, overview 7절 | 영역 문서마다 설계 단위 끝번호(`backend.md §3.5`), 마지막 CF 번호. 이 기능이 붙을 영역 |
| `plan_setup/STATE.md` `Phase Overview` | 끝번호 → 새 phase 는 NN = 끝번호 + 1 |
| 문서 머리 | as-is 표기 여부 — as-is 문서면 이 후미 절이 그 문서의 **첫 "합의된 목표"** 다(아래) |

**as-is 문서에 붙는 추가 절**은 절 첫 줄에 "이 절부터 to-be(합의된 목표)" 한 마디를 둔다. 머리의 as-is 표기는 고치지 않는다 — 앞 절들은 여전히 현재 상태다. 9절의 새 행 상태는 `정의됨` 이다(`구현됨 (as-is)` 가 아니다).
as-is PRD 의 OQ 중 "feature-add 가 채운다" 로 미뤄 둔 것(배경·목표 같은 코드에 없던 칸)이 있으면, 이 기능과 관련된 부분만 후미 절에서 채우고 그 OQ 는 prd-generator 규칙대로 처리한다.

---

## 3단계. 모호하면 — `idea-brainstorm` 후미 절 모드

`docs/IDEA.md` 를 처음부터 다시 쓰지 않는다. 원 프로젝트의 문제·타깃·MVP 범위는 그대로이고, **이 기능 하나에 대한 역질문과 제안**만 후미 절에 남긴다.

```
idea-brainstorm 호출 지시 (feature-add 에서)

- 완료된 프로젝트에 기능 하나를 더하는 요청이다: "<요청 문장>". docs/PRD.md 가 있고 제품 정의는 끝나 있다 — 1~2단계(성숙도 판정·맥락 수집)는 PRD 1·2절과 아래 맥락으로 대신하고, 3~4단계(역질문·방향 제안)를 이 기능에 대해서만 한다
- 역질문은 기능 하나의 축으로 좁힌다: 누가(PRD 2절의 어느 사용자) · 어느 흐름에서(어느 US·화면에 붙는가) · 무엇이 보이고 저장되는가 · 안 하는 것(이번 범위 밖) · 성공 기준
- 제안 2~3안은 "기존 흐름의 어디에 붙는가" 가 서로 달라야 한다. 기존 FR 을 바꾸는 안이면 어느 FR 의 어느 기준이 바뀌는지 적는다
- docs/IDEA.md 후미에 `## 추가 N: <기능>` 절 하나만 붙인다 (N = <값>). 5단계의 문서 구조 중 이 기능에 해당하는 항목(문제 · 타깃 사용자 · 핵심 사용자 흐름 · MVP 범위 포함/제외 · 제약 · 성공 기준 · 리스크와 가정 · 검토된 대안 · 미결)을 그 절 안의 소제목으로 쓴다. 기존 절 본문은 고치지 않는다
- 절 첫 줄: 날짜 · 요청 한 줄 · 선택한 안 · 미결 번호 목록
- docs/IDEA.md 가 없으면(브레인스토밍을 건너뛴 프로젝트, code-to-docs 진입 프로젝트) 머리 한 줄("이 파일은 추가 N 부터 시작한다 — 원 프로젝트의 아이디어 정의는 docs/PRD.md 1절") 아래 그 절만 있는 파일로 만든다
- 6단계 인계: prd-generator 가 아니라 feature-add 로 돌아온다. CLAUDE.md·AGENTS.md 의 `현재 단계` 줄은 feature-add 가 끝에 쓴다
```

끝나면 후미 절의 "MVP 범위 포함" 과 "미결" 을 읽어 요청이 명확해졌는지 1단계의 넷으로 다시 본다. 아직 비면 사용자에게 돌아간다 — PRD 로 밀어 넣지 않는다.

---

## 4단계. `prd-generator` 후미 절 모드 — 항상

기능 추가는 곧 요구 변경이므로 PRD 후미 절은 언제나 생긴다. prd-generator 에는 부분 갱신 단계가 따로 없다 — "1~N단계를 다시 돌리지 말고 후미 절만" 을 지시로 넘기는 **후미 절 모드**로 부른다.
형식(FR 의 다섯 항목, 수용 기준 규칙, OQ 표, 9절)은 그 스킬의 규칙이고 이 스킬은 아래만 넘긴다.

```
prd-generator 호출 지시 (feature-add 에서)

- docs/PRD.md 가 이미 있다. 1~6단계를 다시 돌리지 말고 문서 후미에 `## 추가 N: <기능>` 절 하나만 붙인다 (N = <값>). 입력은 <docs/IDEA.md 의 `## 추가 N` 절 | 요청 문장 "<…>"> 이고 기존 PRD 1·2절이 맥락이다
- 절 첫 줄: 날짜 · 요청 한 줄 · 이 절이 만든 ID 목록(새 US·FR·NFR·OQ, 대체한 FR) · phase-NN-<기능이름>
- 새 US 는 US-<마지막+1> 부터, 새 FR 은 FR-<마지막+1> 부터, 새 NFR 은 NFR-<마지막+1> 부터, 새 OQ 는 OQ-<프로젝트 전체 최댓값+1> 부터(2단계에서 센 값). 3단계 형식(관련 스토리·우선순위·차단 미결·설명·수용 기준)을 그대로 채우고 수용 기준에는 실패 경로를 하나 이상 둔다 — 분리된 세션의 검증자에게는 이 문장이 전부다
- 기존 FR 이 바뀌면 그 절 본문을 고치지 않고 이 절 안에 "FR-003 수용 기준 2 를 다음으로 대체" 로 적는다. **대체는 번호를 유지한다** — FR-003 은 계속 FR-003 이고 뒤 절이 이긴다(새 번호를 주면 9절·태스크·테스트가 전부 옮겨 적어야 한다). 새 번호는 추가 항목에만. 기존 US·FR·NFR·OQ 본문은 고치지 않는다
- 우선순위(P0/P1/P2)는 이 추가 안에서 매긴다 — "이 기능이 없으면 이 추가가 뜻이 없는가". "P0 절반 초과" 점검은 이 절 안에서만 한다
- 이 추가에서 안 하는 것은 절 안의 "범위 밖" 소제목에 둔다(6절 표에 행을 더해도 된다)
- 9절 추적표에 새 FR 행을 더한다 — `담당 태스크` 는 "(Layer 3에서 채움)", `상태` 는 `정의됨`(차단 OQ 가 있으면 `정의됨 (차단)`). **기존 행은 그대로 둔다** — 대체된 FR 의 행도 여기서는 고치지 않는다(plan-generator 가 담당 태스크를 덧붙인다)
- 버전을 올린다(0.1 → 0.2). `상태` 줄은 "사람 검토 대기". as-is 문서면 머리의 as-is 표기는 그대로 두고 절 첫 줄에 "이 절부터 to-be(합의된 목표)"
- 7단계(미결 해소)는 이 절의 새 OQ 에 대해서만 연다. 차단 OQ 는 0 으로 만들고 넘어가되, 안 풀리면 남긴다 — plan-generator 가 그 FR 의 태스크를 blocked 로 만든다
- CLAUDE.md·AGENTS.md 의 `## 제품` 절은 평소대로 갱신하되(P0 개수는 추가 N 의 것을 병기) `현재 단계` 줄은 feature-add 가 끝에 다시 쓴다
```

끝나면 확인할 것은 셋 — 후미 절의 FR 마다 수용 기준에 실패 경로가 있는가, 9절에 새 FR 행이 있고 기존 행이 그대로인가, 대체가 "번호 유지" 형식인가.

---

## 5단계. `trd-generator` 후미 절 모드 — 기술 결정이 새로 생기거나 바뀔 때만

**TD 의 결정이 그대로면 TRD 를 열지 않는다.** 여는 것은 둘 — 새 TD 가 필요하거나, 기존 TD 의 결정 자체가 바뀌어 "TD-00x 를 다음으로 대체" 가 생길 때(예: 오류 코드 규약에 403 이 더해진다, 인증 검사가 쿠키 존재 확인에서 사용자 대조로 바뀐다). 기존 저장소·API 방식·인증으로 만들 수 있는 기능(테이블 하나, 라우트 몇 개, 화면 하나)은 기술 결정이 아니라 설계 단위(6단계)다.
기능 추가마다 TRD 에 절을 붙이면 TRD 가 결정 문서가 아니라 변경 일지가 되고, 뒤 스킬이 어느 TD 가 실제로 바뀌었는지 절 수로 알 수 없게 된다.

**여는 경우** — 새 라이브러리·외부 서비스(메일·푸시·결제), 새 저장 방식(파일 업로드·캐시·큐), 인증·권한 모델의 변경, 새 NFR(성능·보안 수치)을 기존 TD 가 만족시키지 못할 때, 실행 구성이 바뀔 때(프로세스 추가·스케줄러).
판단은 새 FR·NFR 마다 "기존 TD 의 어느 것으로 만드는가" 를 적어 보면 드러난다 — 적을 TD 가 없는 것이 새 TD 이고, 적을 수는 있는데 그 TD 의 결정 문장이 달라져야 하는 것이 대체다. 이 표는 TRD 를 열든 안 열든 보고에 남긴다.

```
trd-generator 호출 지시 (feature-add 에서)

- docs/TRD.md 가 이미 있다. 1~7단계를 다시 돌리지 말고 문서 후미에 `## 추가 N: <기능>` 절 하나만 붙인다 (N = <값>). 근거 요구사항은 docs/PRD.md 의 `## 추가 N` 절(FR-0xx~, NFR-0xx~)이다
- 절 첫 줄: 날짜 · 요청 한 줄 · 이 절이 만든 ID(새 TD·대체한 TD·새 OQ) · phase-NN-<기능이름>
- 새 결정은 TD-<마지막+1> 부터, 3단계의 결정 형식(영역·근거 요구사항·결정·검토한 대안·확정도·되돌리기 비용·검증 방법)을 그대로 채운다. 근거 요구사항이 새 FR·NFR 이 아닌 결정은 만들지 않는다
- 기존 결정이 바뀌면 "TD-00x 를 다음으로 대체" 로 적고 번호를 유지한다. 새 번호는 추가 결정에만. 기존 TD 본문은 고치지 않는다
- 8절 테스트: 새 FR 이 "반드시 덮어야 할 영역" 을 늘리면 그 행을 이 절에 적는다(도구는 그대로). 흐름 목록과 게이트는 harness-update 의 몫
- 9.3 로컬 개발 환경: 새 의존 서비스가 생기면 이 절에 구성 요소 행을 적는다 — harness-update 가 local-dev 에 옮긴다
- 2절 요약 표에 행을 더하고, 13절 추적표에 새 FR → TD 행을 더하고(대체 행은 옛 행 옆에 "→ 추가 N" 병기), 버전을 올린다. 새 OQ 는 OQ-<프로젝트 전체 최댓값+1> 부터(2단계에서 센 값)
- 8단계(미결 해소)는 이 절의 새 OQ 에 대해서만
- CLAUDE.md·AGENTS.md 의 `## 기술` 절은 평소대로. `현재 단계` 줄은 feature-add 가 끝에 다시 쓴다
```

TRD 를 열지 않은 요청은 그 사실과 근거("새 FR 전부 TD-003·TD-005 로 만든다")를 보고에 적는다. N 은 TRD 에서 건너뛴다.

---

## 6단계. `architecture-generator` 9단계 — 새 설계 단위

새 기능은 거의 언제나 새 설계 단위(테이블·라우트·화면 영역)를 만든다. 9단계(부분 갱신)의 규칙이 이미 "새 절은 끝번호, 기존 절은 번호 유지" 이므로 그대로 쓰되, 기존 절의 **본문 수정**은 후미 절의 대체로 돌린다.

```
architecture-generator 호출 지시 (feature-add 에서)

- docs/ARCHITECTURE/ 가 이미 있다. 9단계(부분 갱신)만 한다. 근거는 docs/PRD.md 의 `## 추가 N` 절(과 있으면 docs/TRD.md 의 `## 추가 N` 절)이다
- overview.md 와 이 기능이 붙는 영역 문서의 후미에 `## 추가 N: <기능>` 절을 붙인다 (N = <값>). 첫 줄은 날짜 · 요청 한 줄 · 새 절 번호 목록(`backend.md §3.6`…) · 새 CF·OQ · phase-NN-<기능이름>
- 새 설계 단위는 영역 문서 `## 3. 설계 단위` 의 끝번호에 붙인다(다섯 항목 전부 — 근거·검증 기준·바뀔 수 있는 지점 포함). 검증 기준은 새 FR 의 수용 기준을 가리킨다
- 기존 설계 단위가 바뀌면 그 절 본문을 고치지 않고 후미 절에 "§3.2 를 다음으로 대체"(바뀌는 항목만) 로 적는다. 없어지는 절은 9단계 규칙대로 "폐기 — 대체: §3.y" 표시만 한다.
  기존 절이 가리키던 완료 태스크의 통과 기록이 그 절을 근거로 남아야 한다
- overview 2절 구성·3절 의존 방향에 새 요소·새 방향이 생기면 후미 절에 "다음으로 대체" 표로 적는다. 4절 핵심 흐름은 새 US 마다 후미 절에 흐름 하나
- 7절 CF: 새 절과 기존 절 사이만 검토. 새 CF 는 끝번호. 8절 추적표에 새 FR·NFR → 설계 단위 행을 더한다. 버전을 올린다
- 폐기·대체한 절을 `architecture` 로 가리키는 완료 태스크 목록을 보고에 적는다 — plan-generator 가 색인에 병기한다
- CLAUDE.md·AGENTS.md 의 `## 구조` 절은 평소대로. `현재 단계` 줄은 feature-add 가 끝에 다시 쓴다
```

설계 단위가 하나도 안 생기는 기능(기존 라우트에 필드 하나)은 드물지만 있다 — 그때도 후미 절은 붙인다(어느 §3.x 가 대체되는지가 태스크의 `architecture` 값이 된다).

---

## 7단계. `plan-generator` 10단계 — phase 하나, 태스크는 새 설계 단위에서

plan-generator 는 평소처럼 자기 절차(설계 단위에서 태스크 자르기·frontmatter·phase 문서·STATE.md 행 추가·LOG.md 한 줄·PRD 9절·자체 점검·보고)를 다 한다. 이 스킬은 아래만 넘긴다.
리팩토링과 달리 **통과 조건은 새 FR 의 수용 기준**이라 plan-generator 의 기본 동작에 가깝다 — 지시는 "어디를 읽는가" 와 "무엇을 건드리지 않는가" 다.

```
plan-generator 호출 지시 (feature-add 에서)

- plan_setup/ 이 이미 있다. 10단계(부분 갱신)만 한다. 완료된 phase·태스크는 건드리지 않는다
- 입력은 세 문서의 `## 추가 N` 절과 그 절이 만든 설계 단위(§3.x 끝번호 절)뿐이다. 앞 절은 번호·이름을 참조하는 데만 읽는다
- phase 하나를 끝번호로 더한다: phase-NN, 파일 이름 phase-NN-<기능이름>.md (NN = Phase Overview 끝번호 + 1, <기능이름> 은 영문 kebab-case). phase 문서 머리에 "추가 N: <기능>" 과 후미 절 위치(IDEA/PRD/TRD/ARCHITECTURE 의 절)를 적는다. Dependencies 는 완료된 phase 전부(기존 코드 위에 붙는다)와, 같은 파일을 만지는 pending phase 가 있으면 그것
- 태스크는 3단계 규칙대로 새 설계 단위에서 자른다. acceptance_criteria 는 `## 추가 N` 절의 FR 수용 기준(대체된 기준 포함)에서 가져오고 architecture 는 새 §3.x(대체된 절이면 그 절 번호)를 가리킨다
- 대체된 FR 이 있으면 그 기준을 구현하는 태스크가 phase 안에 있어야 하고, 그 FR 의 현행 고정 테스트(phase-01 의 as-is 테스트, 또는 기존 테스트)를 새 기준으로 바꾸는 것이 그 태스크의 files 에 들어간다 — 안 바꾸면 게이트가 옛 동작을 지킨다
- 차단 판정은 2단계 규칙 그대로 — `## 추가 N` 절의 차단 OQ·새 CF 에 걸린 태스크는 blocked
- PRD 9절: 새 FR 행의 `담당 태스크`·`상태`(계획됨) 를 7단계 규칙대로 채운다. 대체된 기존 FR 의 행은 `담당 태스크` 열에 새 태스크를 덧붙이는 것까지만 — 다른 열은 그대로. PLAN.md 6절 추적표에도 새 FR 행을 더한다
- phase 의 Acceptance Criteria: 태스크 전부 completed, 게이트 넷 통과, `## 추가 N` 절의 FR 수용 기준 전부 PASS, 기존 FR 의 테스트가 대체된 것 외에는 그대로 통과
- STATE.md 의 Phase Overview 에 phase-NN pending 행을 더한다. Current Phase 는 옮기지 않는다(루프의 것). LOG.md 에 "플랜 갱신 — 추가 N phase-NN 추가, 태스크 n개, blocked k건" 한 줄
- 폐기·대체된 §3.x 를 가리키는 완료 태스크는 색인에 "(설계 §3.x → 추가 N 에서 대체)" 병기
- CLAUDE.md·AGENTS.md 의 `## 플랜` 절은 평소대로. `현재 단계` 줄은 feature-add 가 끝에 다시 쓴다
```

plan-generator 가 끝나면 보고를 그대로 전한다. 확인할 것은 넷 — phase 가 하나 늘었는가, 후미 절의 FR 마다 담당 태스크가 있는가(9절 새 행 전부 `계획됨`), 완료된 phase·태스크가 바이트 단위로 그대로인가, STATE.md 에 pending 행이 더해졌는가.

---

## 8단계. `harness-update` · `loop-update` 호출

둘 다 평소대로 자기 절차를 한다. 넘길 것은 이 추가가 바꾸는 것뿐이다.

```
harness-update 호출 지시 (feature-add 에서)

- phase-NN-<기능이름> 이 추가됐다. 새 FR: <목록>, 대체된 FR: <목록>, 새 US: <목록>. docs/PRD.md `## 추가 N` 절이 근거다
- 새 FR·US 를 덮는 E2E 흐름과 unit 필수 커버 영역을 더한다(②) — 상태는 `대기`, 활성 시점은 phase-NN 의 해당 태스크 ID. 대체된 FR 의 기존 흐름·검사는 그 태스크가 완료되면 새 기준으로 판정된다는 것을 적는다(단언을 지금 빼지 않는다 — ③ 가 아니다)
- 새 의존 서비스(TRD `## 추가 N` 의 9.3 행)가 있으면 HARNESS.md 구성 요소 표와 local-dev 에 더한다(②)
- 새 화면·API 의 task_validation 관찰 수단이 기존 정의서로 충분한지 본다 — 부족하면 더한다(②)
- 활성 시점·게이트 명령은 그대로. 약화(③)는 없다
```

```
loop-update 호출 지시 (feature-add 에서)

- 태스크가 늘었다. DAG 를 스크립트로 다시 만들고 자원 충돌 표·구간별 폭을 다시 잰다 — 새 기능 태스크는 기존 파일(라우터·화면·스키마)을 여럿 만지므로 files 겹침을 본다
- phase-NN 의 blocked 태스크가 있으면 막다른 곳 서술에 그 OQ 를 적는다
- phase-NN 이 completed 되면 루프를 멈추고 사용자에게 돌아온다
```

---

## 9단계. `CLAUDE.md` · `AGENTS.md` — `현재 단계` 줄

이 스킬은 자기 절이 없다. 제품·기술·구조·플랜·하네스·루프 절은 3~8단계에서 부른 스킬이 각자 갱신한다.
이 스킬이 하는 것은 **맨 끝에 `현재 단계` 줄을 덮어쓰는 것** 하나다 — 중간에 부른 plan-generator 가 그 줄을 "plan-generator → 다음: harness-setup" 으로 썼고 update 계열은 그 줄을 건드리지 않으므로, 끝에서 한 번 더 쓴다. 두 파일 다.

```
- 현재 단계: feature-add(추가 N: <기능> → phase-NN) → 다음: 개발 루프 (phase-NN-<기능이름>)
```

두 파일이 서로 다르면 지금 호스트의 파일을 기준으로 다른 쪽을 맞추되 손으로 적은 줄은 양쪽에 남긴다. 파일이 없으면(부른 스킬이 뼈대를 만들었을 것이다) 그 뼈대 위에 쓴다. 200줄을 넘기지 않는다.

---

## 10단계. 자체 점검과 보고

전부 끝나면 처음부터 다시 읽으면서 확인한다. 열은 `확인할 것 | 통과 조건 | 걸렸을 때` 다.

| 확인할 것 | 통과 조건 | 걸렸을 때 |
|---|---|---|
| 진입 조건 | `in_progress` phase 0건, 네 문서·디렉터리 존재 | 0단계로 돌아가 멈춘다 |
| 경로 판정 | 모호하면 IDEA.md 후미 절이 있고, 명확하면 없다. 리팩토링·버그가 섞인 문장은 보고의 "일부러 넣지 않은 것" 에 | 되돌리거나 보고에 옮긴다 |
| N | 모든 후미 절이 같은 N. `docs/` 전체에서 `## 추가 N` 이 이 요청 것뿐(중복 없음) | 번호를 맞춘다 |
| 후미 절 | 요청이 요구하는 문서에만 `## 추가 N` 이 있고 첫 줄에 날짜·요청·ID·phase. 기존 절 본문 변경 0(9단계의 "폐기 — 대체" 표시와 표의 행 추가·버전 줄 제외) | 되돌리고 후미 절로 옮긴다 |
| 번호 이어짐 | 새 US·FR·NFR·OQ·TD·CF·§3.x 가 전부 기존 마지막 다음. 대체는 "FR-00x 수용 기준 n 을 다음으로 대체" 형식이고 번호 유지 | 고친다 |
| 수용 기준 | 새 FR 마다 관찰 가능한 기준 + 실패 경로 1개 이상 | prd-generator 후미 절 모드로 돌아간다 |
| PRD 9절 | 새 FR 행이 있고 `담당 태스크`·`상태(계획됨)` 가 채워짐. 기존 행은 그대로(대체된 FR 의 담당 태스크 덧붙임 제외) | plan-generator 10단계 |
| TRD | 새 TD 가 없으면 바이트 단위로 그대로. 있으면 후미 절과 2절·13절 행·버전 | 열지 말았어야 하면 되돌린다 |
| phase | `plan_setup/phase-NN/phase-NN-<기능이름>.md` 가 끝번호이고 영문 이름. 완료된 phase 는 바이트 단위로 그대로 | plan-generator 10단계 |
| 태스크 | 새 FR 마다 담당 태스크. `acceptance_criteria` 가 후미 절의 기준에서 옴. 대체된 FR 의 현행 고정 테스트를 바꾸는 태스크가 있음. `verification` 넷 | plan-generator 10단계 |
| STATE.md | `Phase Overview` 에 phase-NN `pending` 행. 다른 절 그대로 | plan-generator 10단계 |
| 하네스·루프 | 새 흐름·커버 영역이 `대기` 로 있고 활성 시점이 phase-NN 태스크. `DAG.md` 에 phase-NN 태스크 | harness-update·loop-update |
| `현재 단계` 줄 | `CLAUDE.md`·`AGENTS.md` 둘 다 9단계 값, 두 파일이 같음 | 덮어쓴다 |

**자체 점검 결과는 문서에 남기지 않는다.** 보고로 간다.

보고는 이렇게 한다.

1. 요청과 판정 — 모호/명확, 어느 스킬부터 갔는가, 추가 N, 기능 이름(한글/영문)
2. 문서 — 후미 절을 붙인 문서와 새 ID(US·FR·NFR·OQ·TD·§3.x), 대체한 항목. 안 붙인 문서와 이유("새 TD 없음 — FR-015~017 은 TD-003·TD-005 로")
3. phase-NN — 태스크 n개, blocked k건(어느 OQ), 순서(depends_on), 대체된 FR 의 테스트를 바꾸는 태스크
4. 하네스·루프 — 더한 흐름·커버 영역과 활성 시점, 새 의존 서비스, DAG 폭
5. **문서에 일부러 넣지 않은 것** — 리팩토링(`refactor-plan`)·버그(`bug-fix`)로 보낸 것. 요청 문장을 그대로 옮겨 다음 스킬에서 다시 설명하지 않게. 게이트가 미활성이었으면 그 사실
6. 미결 — 새 OQ 중 차단인 것과 그것이 막는 태스크
7. 다음: "문서·플랜·하네스·루프의 변경을 커밋한 뒤 루프를 돌려 phase-NN 을 완료시키세요(병렬이면 워커 트리는 커밋된 문서만 봅니다). 차단 OQ 가 있으면 먼저 푸는 편이 phase 가 한 번에 끝납니다"

---

## 범위를 넘는 요청이 함께 오면

기능 추가 요청은 다른 것과 같이 오는 일이 많다. **하지 않고, 어디로 가는지 답한다.** 조용히 무시하지도, 조용히 하지도 않는다.

| 요청 | 이 스킬이 하는 것 | 왜 |
|---|---|---|
| "댓글 넣으면서 라우터 정리도" | 댓글만. 정리는 `refactor-plan`. 문장을 보고에 그대로 옮긴다 | 정리 태스크는 통과 조건이 "기존 게이트 통과" 라 기능 phase 의 수용 기준과 섞이지 않는다 |
| "추가하는 김에 이 버그도" | phase 에 넣지 않는다. `bug-fix`(지금 먼저, 또는 phase 완료 뒤) | 버그 수정은 회귀 검사·BUG-NN 기록·분리 검증이 따른다. 기능 태스크에 섞이면 셋 다 빠진다. 단 as-is 문서에 관찰대로 적힌 동작을 바꾸는 것은 버그가 아니라 요구 변경이다 — 이 스킬이 "대체" 로 받는다 |
| "PRD 를 새로 써 줘, 처음부터" | 하지 않는다. 후미 절만 | 완료된 태스크가 가리키는 절이 사라지고 번호가 흔들린다. 전체를 다시 쓰는 것은 새 프로젝트다 |
| "기능 여러 개 한 번에" | 요청마다 N 하나, phase 하나. 서로 독립이면 N 을 여럿 배정하고 순서대로 | 한 phase 에 기능 셋이 들어가면 phase 수용 기준이 "이것과 저것과 그것" 이 되어 자동 판정을 못 한다. 같이 가야만 뜻이 있는 것은 하나로 |
| "문서는 됐고 바로 만들어 줘" | 후미 절과 phase 는 만든다 | 루프는 태스크 문서와 수용 기준을 읽고 움직인다. 문서 없이는 무엇을 만들었는지 판정할 검증자가 없다 |

---

## 산출물 요약

이 스킬이 직접 쓰는 것은 없다 — 문서·플랜·하네스·루프는 부른 스킬의 형식이다. 여기서는 **후미 절의 모양**만 보여 준다. 소제목과 항목은 각 스킬의 본문 형식을 그대로 따르고, 절 첫 줄만 이 스킬이 정한다.

### `docs/IDEA.md` 후미 절 (모호한 요청일 때)

```markdown
## 추가 1: 연체 알림

- **날짜**: YYYY-MM-DD · **요청**: "뭔가 알림 같은 걸 넣고 싶은데" · **선택한 안**: B안(앱 내 배지 + 메일) · **미결**: 1~2

### 문제
(이 기능이 없어서 지금 무엇이 불편한가 — 원 프로젝트의 문제 절은 그대로다)
### 타깃 사용자
### 핵심 사용자 흐름
### MVP 범위 — 포함 / 제외
### 검토된 대안 방향
### 미결 사항
```

### `docs/PRD.md` 후미 절 + 9절 행

```markdown
## 추가 1: 댓글

- **날짜**: YYYY-MM-DD · **요청**: "댓글 기능 추가하려는데" · **이 절이 만든 ID**: US-007, FR-015~FR-017, OQ-012 · FR-007 수용 기준 3 대체 · **phase**: phase-02-comments
- (as-is 문서면) 이 절부터 to-be(합의된 목표)

### 유저 스토리
| ID | 사용자 | 스토리 | 우선순위 |
|---|---|---|---|
| US-007 | 팀원 | 할 일에 댓글을 남기고 싶다. 왜냐하면 … | P0 |

### 기능 요구사항
#### FR-015. 할 일에 댓글 작성
- **관련 스토리**: US-007
- **우선순위**: P0
- **차단 미결**: 없음
- **설명**: …
- **수용 기준**:
  - [ ] …
  - [ ] 빈 본문이면 400 을 반환하고 저장되지 않는다

### FR-007 수용 기준 3 을 다음으로 대체
- [ ] 할 일 목록의 각 항목에 댓글 수가 표시된다 (0 이면 표시하지 않는다)

### 범위 밖
| 항목 | 이유 | 언제 다시 볼 것인가 |

### 미결 사항
| ID | 결정할 것 | 종류 | 차단하는 요구사항 | 해소 방법 | 미해소 시 기본값 | 되돌리기 비용 |
| OQ-012 | … | 질문(잠정) | FR-016 | … | … | … |
```

9절 추적표에는 `| FR-015 | US-007 | P0 | — | (Layer 3에서 채움) | 정의됨 |` 행이 더해지고, 기존 행은 그대로다(버전 0.2 — prd-generator 규칙).

### `docs/TRD.md` 후미 절 (새 TD 또는 TD 대체가 있을 때만)

```markdown
## 추가 1: 연체 알림

- **날짜**: YYYY-MM-DD · **요청**: "연체 시 메일 알림" · **이 절이 만든 ID**: TD-011, OQ-013 · **phase**: phase-07-overdue-notice

#### TD-011. 메일 발송: 외부 트랜잭션 메일 API
- **영역**: 스택 · **근거 요구사항**: FR-025, NFR-017 · **결정**: … · **검토한 대안**: … · **확정도**: 잠정(OQ-013 대기) · **되돌리기 비용**: … · **검증 방법**: …

(2절 요약 표 행 추가 · 13절 추적표 FR-025 → TD-011 · 버전 올림 — trd-generator 규칙)
```

### `docs/ARCHITECTURE/overview.md` · 영역 문서 후미 절

```markdown
## 추가 1: 댓글

- **날짜**: YYYY-MM-DD · **요청**: "댓글 기능 추가하려는데" · **이 절이 만든 ID**: backend.md §3.6·§3.7, frontend.md §3.7 (신설), CF 없음 · **phase**: phase-02-comments

### 2절 시스템 구성에 더하는 것
| 요소 | 역할 | 근거 |
### 4절 핵심 흐름 — US-007 댓글 작성
1. …
### backend.md §3.3 을 다음으로 대체
- 할 일 삭제 시 그 할 일의 댓글도 함께 삭제한다 (FR-017)
```

영역 문서의 `## 3. 설계 단위` 에는 `### 3.6 댓글 저장과 조회 (routes/comments.js)` 가 끝번호로 붙는다(다섯 항목 전부 — architecture-generator 9단계 규칙).

### `plan_setup/phase-NN/phase-NN-<기능이름>.md` 머리

```markdown
# Phase 02 — comments (추가 1: 댓글)

- **Goal**: 할 일에 댓글을 달고 보고 지운다. 기준 문서: docs/PRD.md·docs/ARCHITECTURE/{overview,backend,frontend}.md 의 `## 추가 1`
- **Dependencies**: phase-01 (기존 코드·게이트)
- **Status**: pending

## Acceptance Criteria
1. 태스크 전부 completed
2. lint·unit·e2e 통과
3. FR-015~FR-017 수용 기준 전부 PASS (task_validation)
4. FR-007 의 현행 고정 테스트가 대체된 기준으로 바뀌어 통과, 나머지 기존 테스트는 그대로 통과
```

---

## 에이전트별 참고

- Claude Code에서 실행 중이면: `references/claude-code.md`
- Codex에서 실행 중이면: `references/codex.md`