---
name: feature-add
description: 기존 프로젝트의 기능 추가·요구 변경을 영향 범위만 계획하고 반영한다. 기존 ID와 완료 이력을 보존하며 실행 요청이면 구현·검증까지 완료한다.
---

# 기존 프로젝트 기능 추가

## 목적과 입력

기존 기능과 진행 상태를 보존하면서 요청한 동작을 추가하거나 변경한다.
요청, 관련 코드·문서·테스트, 진행 중 계획과 운영 합의를 읽는다.
프로젝트 전체 완료나 PRD·하네스·루프의 존재를 진입 조건으로 삼지 않는다.

## 최소 산출물

- 영향 요구에 요청·포함/제외·새/대체 요구·관찰 가능한 수용 기준을 남긴다.
  요구 문서가 없으면 `docs/PRD.md`에 필요한 범위부터 짧게 만든다.
- 추적할 변경은 `## 추가 N: <기능>` 후미 절로 연결한다. 기술 결정이 변하면 `docs/TRD.md`,
  경계·흐름·계약이 변하면 `docs/ARCHITECTURE/`의 영향 부분만 보완한다.
- 계획 관리가 필요하면 끝번호 `plan_setup/phase-NN/phase-NN-<기능이름>.md`와 필요한 태스크를 추가한다.
  `PLAN.md`·`STATE.md`·`LOG.md`의 관련 색인·상태·증거만 갱신한다.
- 작은 변경은 기존 요구/작업의 짧은 갱신으로 충분하다. 후미 절·새 phase·모든 레이어 호출을 강제하지 않는다.
  실행 요청이면 코드·테스트·실제 수용/회귀 결과, 문서·계획만 요청이면 해당 문서가 산출물이다.

## 진행

1. 기존 기능과 요청의 차이를 확인한다. 이미 구현/계획된 기능을 다시 만들지 않는다.
   현재 동작·합의된 목표·미확인 의도를 구분하고 사용자 요청으로 확정된 변경을 기록한다.
2. 대상 사용자·동작·흐름·수용 기준이 명확하면 바로 요구를 쓴다.
   방향이 모호할 때만 `idea-brainstorm`의 필요한 절차로 좁히고 `docs/IDEA.md`에 남긴다.
   코드 관찰과 추론한 목적을 구분한다. 명확한 작은 기능에 IDEA를 강제하지 않는다.
3. 사용자만 정할 범위·권한·비용·데이터 경계를 실행 전에 해소하고 기존 합의를 재사용한다.
   OS·설치·실행 방법 등 사실은 조사하며 무응답을 승인으로 간주하지 않는다.
4. 후미 절을 쓰면 `추가 N`은 기존 추가 번호 최댓값 다음이며 영향 문서에 같은 번호를 쓴다.
   FR/NFR/US/TD/OQ/CF는 끝번호를 이어 쓴다. OQ는 기존 harness/loop까지 확인해 충돌을 피한다.
   기존 요구 교체는 번호를 유지하고 `FR-… 수용 기준 …을 다음으로 대체`처럼 연결한다. 대체된 요구·TD의 원래 위치에 현재 기준 포인터를 둔다.
5. 정상 흐름과 중요한 실패 경로의 관찰 결과를 요구에 쓴다. 기술 선택은 TRD, 계약은 Architecture,
   구현 순서와 검증 단위는 Plan에 둔다. 영향 없는 문서는 열지 않고 같은 내용을 반복하지 않는다.
6. 기능을 실행으로 검증할 단위로 묶고 실제 선행 관계만 둔다. 여러 파일을 한 태스크로 바꿀 수 있다.
   새 태스크 필수 키는 `id`, `status`, `depends_on`, `acceptance_criteria`, `verification`이다.
   기존 확장 필드·완료 이력·상태를 보존한다.
7. 새 검사·명령·환경이 필요할 때만 harness를, 운영·의존 조정이 필요할 때만 loop를 보완한다.
   없는 산출물은 필요한 부분만 만든다. 관련 스킬을 읽거나 호출해 수행하며 전체 호출을 강제하지 않는다.
   요청 범위를 넘어 다음 단계·스킬로 넘어갈 때는 사용자가 명시적으로 승인한 범위가 아니면 결과와 다음 단계를 제안해 승인을 받는다. Loop 시작 후에는 자율로 진행한다.
8. 실행 요청이면 구현 → 필요한 검사 → 실제 수용 관찰 → 상태/증거 갱신까지 이어 간다.
   변경 기준의 기존 테스트는 근거와 함께 갱신하고 나머지 동작의 회귀를 확인한다.
   다음 스킬이나 루프를 사용자가 실행하라는 안내만 남기고 끝내지 않는다.

## 필수 제약

- 기존 ID·절 참조·완료 이력·사용자 편집·메모·후미 절을 보존한다. 과거 근거가 되는 본문은 유지하며 교체/폐기를 연결한다.
  색인·상태는 영향 행만 갱신한다. 전체 재생성이나 양쪽 루트 지침 동기화를 요구하지 않는다.
- 문서 없는 코드도 관련 동작을 조사해 바로 진행할 수 있다. 전체 `code-to-docs`나 현행 고정 phase는 필수가 아니다.
- 함께 요청된 버그·리팩토링은 해당 기준과 회귀 증거를 구분해 필요한 절차를 이어 수행한다.
  여러 기능도 실제 의존과 검증 가능성으로 묶으며 요청마다 별도 세션/phase를 기계적으로 늘리지 않는다.
- `in_progress`·미커밋만으로 중단하지 않는다. 실제 실행 주체·소유권·충돌 범위를 조사한다.
  공유 상태는 기존 필자가 안전한 경계에서 반영하게 조율하고 독립 준비를 진행한다.
  겹치는 작업만 직렬화하며 기존 실행을 빼앗거나 사용자 변경을 되돌리지 않는다.
- Loop 이후 합의 안에서는 질문·재승인·수동 실행 요청 없이 복구한다. 권한과 예산은 우회하지 않는다.
  새 결정 없이는 못 하는 작업/의존만 차단하고 독립 작업 후 증거·재개 조건이 있는 미완료로 종료한다.
- 작은 독립 기능에는 전체 문서 파이프라인·네 게이트·자식 실행을 강제하지 않는다. 기존 Loop 제품 변경은 아래 계약을 따른다.

- 시작·중요한 범위/결정·검증·분석 전환에서 해당 문서 또는 기존 STATE/LOG를 증분 저장한다.
  현재 단계·확정/미결·누적 시도/전략·사용/잔여 예산·다음 행동과 대상 코드/지속 증거를 연결한다.
  새 세션은 이 기록과 실제 코드·미커밋·살아 있는 실행/미반영 결과를 대조해 이어가며 완료·실패 이력을 초기화하지 않는다.
  작은 문서/계획 요청은 해당 문서의 짧은 재개 기록으로 충분하며 전체 계획 체계를 만들지 않는다.

화면 기능은 디자인 정본의 확인된 승인 범위·품질 기준 안에서 기존 승인을 재사용하고 현행 문서만으로 승인을 추정하지 않는다.
새 방향·범위 밖 시각 변경은 PRD의 실제 미리보기·사용자 확정을 본격적인 화면 구현·관련 Loop 전에 확보한다. 작은 독립 요청도 필요한 디자인 결정을 생략하지 않는다.

## 기존 Loop의 제품 변경

현재 요청·유효한 합의·태스크 연결상 기존 Loop의 재개·추가·검증·복구에 속하는 제품 변경은 계약을 계승한다.
LOOP.md의 존재나 과거 완료 이력만으로 새 독립 요청을 편입하지 않는다. 적용 범위와 근거를 기록하고 Loop 작업을 작게 나눠 면제하지 않는다.
`loop_setup/LOOP.md`·STATE와 HARNESS를 읽고 `lint → unit → e2e → task_validation` 판정 순서를 계승한다.
task_validation은 해당 변경 미구현·구현 대화/추론/자체 통과 결론을 비상속한 별도 세션이 맡는다. 앞 실패 뒤 후행 완료 판정을 하지 않는다.
환경 선택(Orca/일반/Others)·충돌/자원 조건·누적 시도와 전체 예산을 보존한다. 같은 방식의 수정은 3회 이내 심층 분석·새 전략으로 전환하며 이력/예산을 초기화하지 않는다.
상세 검증·복구·배정은 `harness-setup`·`harness-update`·`loop-setup`·`loop-update`의 필요한 절차로 이어 수행한다.
새 사용자 지시·계획만·자식 실행 금지가 우선하며 변경된 보장과 미검증을 기록한다. 금지된 실행을 강행하거나 독립 검증 PASS를 꾸미지 않는다.

## 완료 증거

계획 요청은 요구 → 영향 설계/작업 → 검증 방법의 연결로 완료를 판정한다.
실행 요청은 실제 성공·실패 경로와 관련 회귀 검사로 입증한다. 미실행·환경 실패·0건 검사를 통과로 세지 않는다.
변경 범위·대체 기준·실행 결과·미완료와 재개 지점을 보고한다.

## 환경 참고

- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)