변경 (브라운필드)은(는) 무엇을 하나요?

새로운 PRD를 작성하지 않고 기존 명세와 코드베이스에 제한적이고 검토 가능한 변경을 추가합니다. 하나의 변경은 하나의 제안서와 정확히 하나의 4개 문서 작업 번들을 생성합니다. QA가 통과하면 확인된 델타가 명세에 기록되고 제안서는 보관됩니다. 이 스킬은 프롬프트 우선입니다: 각 단계에 수동 대체 방법이 있으며 번들 스크립트는 선택적 도우미입니다.

파이프라인 위치: spec-generator -> change -> task-decomposition -> plan-linter (게이트 1) -> review (게이트 2) -> dev -> qa -> converge -> 보관

기존 명세 + 제한된 변경
  -> .specs/change-context/standards.md        (standards_extract.py; 암묵적 제약 조건)
  -> .specs/changes/<change-id>/proposal.md    (생명주기: proposed -> applied -> archived)
  -> tasks/<change-id>/01..04                  (하나의 계약, 하나의 번들)
  -> 게이트 1 plan-linter -> 게이트 2 review -> dev <-> qa -> converge -> 보관된 제안서

다음 경우에 사용

기존 명세나 출시된 코드베이스에 점진적 변경(버그 수정, 소규모 기능, 동작 조정, 제한된 NFR 조정)이 필요한 경우.
변경 내용이 기존 #sec-* 앵커를 재사용할 수 있고 마이크로/표준 차이 예산에 적합한 경우.
제안서 -> 적용 -> 보관 루프를 사용하면서 이 저장소의 4개 문서 작업 프로토콜과 파일당 단일 소유자 역할을 유지하려는 경우.

다음 경우에는 사용하지 마십시오

그린필드 작업이거나 상위 명세가 아직 존재하지 않는 경우: prd-generator, spec-generator, task-decomposition을 순서대로 사용하십시오.
변경에 새로운 아키텍처 결정, 새로운 컴포넌트 경계, 새로운 교차 관심사 불변 조건, 또는 완전히 새로운 명세 섹션(새 #sec-* 앵커)이 필요한 경우: spec-generator로 에스컬레이션하고 변경에 끼워 넣지 마십시오.
승인된 명세를 작업으로만 분할해야 하는 경우: task-decomposition을 사용하십시오.
기존 번들이나 제안서만 감사해야 하는 경우: plan-linter를 사용하십시오.
작업이 이미 계획되어 구현/검증을 기다리고 있는 경우: dev / qa를 사용하십시오.

입력

기본 명세: 기본값은 .specs/02-tech-spec.md (및 해당 모듈식 부분).
요청자가 일반 언어로 작성한 제한된 변경 요구사항.
1단계에서 생성된 저장소 규칙 보고서.
선택사항: 변경이 계속되는 기존 작업 번들 및 관련 ADR.

출력

아티팩트	스캐폴딩 후 소유자	목적
`.specs/change-context/standards.md`	도구	결정론적 저장소 표준 및 암묵적 제약 조건 (생성됨, 수동 편집 금지).
`.specs/changes/<change-id>/proposal.md`	기획자	제한된 변경 제안서: 동기, 증분 차이, 영향 범위, 불변 조건/NFR, 롤백, 검증.
`.specs/changes/<change-id>/convergence.md`	수렴 도구	QA 통과 후 작성됨; 명세에 다시 통합된 내용을 기록.
`tasks/<change-id>/01-contract.md` ... `04-process.md`	기획자 / 개발 / QA / 도구	정확히 하나의 4개 문서 번들, task-decomposition 템플릿 재사용.

제안서는 PRD가 아니며 대체 명세도 아닙니다. 변경하는 기존 앵커를 명명하는 델타입니다. 전체 생명주기 및 크기 규칙: references/brownfield-protocol.md.

워크플로우

저장소 표준 추출 (구성 변경당 한 번):
```
python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
```
계획을 세우기 전에 .specs/change-context/standards.md를 읽으십시오. "암묵적 제약 조건" 섹션은 바인딩됩니다: 증거된 명령어만 사용하고, 선언된 테스트 레이아웃, 런타임 최소 요구 사항 및 기존 앵커를 존중하십시오. --check의 종료 코드 1은 보고서가 오래되었음을 의미합니다. 계획을 세우기 전에 다시 생성하십시오. 보고서를 수동으로 편집하지 마십시오.
제안서 및 하나의 작업 번들 스캐폴딩 (파일을 쓰는 유일한 단계):
```
python .agents/skills/change/scripts/scaffold_change.py \
  --change-id CHG-001-rate-limit \
  --title "로그인 시도 속도 제한" \
  --anchor "#sec-auth-tokens" \
  --kind modify \
  --size-class micro --estimated-lines 40 \
  --touch-files "modify:src/auth/rate_limit.py" \
  --repo-root .
```
스캐폴더는 기본 명세에 대해 앵커를 검증하고 base_spec_sha256을 계산하며, task-decomposition(scaffold_task.py)에 위임하거나 없는 경우 최소 인라인 번들을 생성합니다. 미리 보려면 --dry-run을, 일회성 실행을 덮어쓰려면 --force를 사용하십시오.
기획자가 제안서와 계약을 작성합니다. 제안서의 가이드(motivation, [CHG-<n>] 청크, 경로, 불변 조건/NFR, 롤백, 검증)와 계약 자리 표시자(module, adherence_adrs, dod, 엣지 케이스, 불변 조건 설명)를 대체하십시오. 경로나 앵커를 임의로 만들지 마십시오. 02/03 빈 역할 양식은 그대로 두고, 제안서 status: proposed도 유지하십시오.

게이트 1, 게이트 2. 결정론적 게이트 1을 실행한 다음 독립적인 의미 검토를 실행합니다:

# 저장소 루트에서 실행합니다. 게이트 1 도우미는 plan-linter 스킬이 설치되어 있어야 합니다.
python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .

게이트 1은 구현 전에 통과해야 합니다. 게이트 2는 BLOCKED 또는 REQUEST CHANGES를 보고하지 않아야 합니다.

구현 및 검증. dev(선언된 touch_files만, 02 작성, 인계)와 qa(tests/acceptance/ 아래 독립 테스트, 03 작성, 하나의 평결)를 실행합니다. 구현 및 검증이 통과되면 제안서는 applied로 전환됩니다.
수렴 및 보관. QA_PASSED 후 converge를 실행하여 확인된 편차를 .specs/02-tech-spec.md에 추가하고, convergence.md를 작성하며, 번들을 tasks/archive/로 이동하고, 제안서 status: archived를 설정합니다. converge가 없으면 동일한 추가 쓰기-백을 수동으로 수행합니다.

수동 대체 방법 (Python 없음)

저장소 루트 구성, 테스트/소스 트리, 런타임, #sec-* 앵커를 수동으로 표준 목록을 작성합니다.
assets/templates/proposal.template.md를 .specs/changes/<change-id>/proposal.md로 복사하고 모든 토큰({{...}})을 채우고 base_spec_sha256을 계산합니다.
task-decomposition 템플릿 또는 references/brownfield-protocol.md의 대체 방법을 사용하여 tasks/<change-id>/ 4개 문서 번들을 생성합니다.
게이트 1 / 게이트 2 체크리스트를 수동으로 실행하고 증거를 번들에 기록합니다.
동일한 아티팩트로 워크플로우 5-6단계를 따릅니다.

품질 게이트 체크리스트

표준 보고서가 생성되었고 최신 상태입니다(standards_extract.py --check 종료 코드 0).
제안서 앞부분이 완료되었고, status: proposed, kind가 올바르며, base_spec_sha256이 최신입니다.
모든 [CHG-<n>] 블록이 기본 명세에 존재하는 실제 #sec-* 앵커를 지정합니다.
정확히 하나의 작업 번들이 존재합니다. change_id는 제안서 ID와 같고 origin_spec_anchor는 제안서의 impact_anchors 중 하나입니다.
차이 예산이 준수됩니다: 마이크로는 1개 터치 파일(기본값 10-49줄); 표준은 1-3개 파일(기본값 50-250줄). 숫자는 plan-linter 구성에서 설정 가능합니다.
게이트 1이 채워진 계약에서 통과하고 제안서가 열려 있습니다(proposed/applied).
게이트 2 검토에 차단 결과가 없습니다. 검토자는 독립적이고 읽기 전용입니다.
개발은 touch_files만 구현했습니다. QA는 증거와 함께 정확히 하나의 평결을 발행했습니다.
수렴이 명세에 델타를 추가했고 제안서가 archived입니다.

할루시네이션 방지 규칙

파일 경로를 절대 임의로 만들지 마십시오. 모든 touch_files 항목은 modify할 기존 파일이거나 create할 기존 디렉토리의 새 파일이어야 합니다(저장소 기준, 슬래시 사용).
모든 diff 청크는 실제 앵커를 지정합니다. 기존 #sec-* 앵커를 재사용하십시오. 스캐폴더와 린터는 누락되거나 이동된 앵커를 거부합니다.
명령어나 규칙을 임의로 만들지 마십시오. 선언된 구성(표준 보고서)에 의해 증거된 명령어만 계약의 DoD에 나타날 수 있습니다.
구조적 변경은 에스컬레이션됩니다. 변경에 새 명세 섹션/앵커, 새 컴포넌트, 새 ADR 또는 불변 조건 변경이 필요한 경우 중단하고 spec-generator를 사용하십시오.
게이트를 과장하지 마십시오. 게이트 1은 결정론적 부기, 게이트 2는 프롬프트 검토입니다. Git과 CI는 여전히 권위적입니다.

도우미 스크립트

scripts/standards_extract.py — 결정론적 표준 추출기; .specs/change-context/standards.md를 작성합니다(--json, --check, --dry-run, --version).
scripts/scaffold_change.py — 제안서와 하나의 작업 번들을 생성합니다(--dry-run, --force, --json, --version).
scripts/lint_change.py — 제안서/번들 일관성 및 기본 명세 드리프트 검사(--json, --version).

모든 도우미는 stdlib 전용이며, 자체 디렉토리를 확인하고 종료 코드 0(성공), 1(게이트 실패), 2(사용법 오류), 3(예기치 않은 오류)으로 종료됩니다.

실패 처리

기본 명세 누락: 중단. 브라운필드 변경에는 기본 명세가 필요합니다. 스캐폴드가 2로 종료됩니다.
알 수 없는 앵커: 중단하고 기존 앵커를 재사용하거나 spec-generator로 에스컬레이션합니다.
오래된 보고서 또는 명세 드리프트(종료 코드 1): 보고서를 다시 생성하고, 제안서를 리베이스하고, 게이트 1을 다시 실행합니다. base_spec_sha256을 수동으로 편집하지 마십시오.
변경 디렉토리가 이미 존재함: 일회성인 경우에만 --force로 다시 실행합니다. 그렇지 않으면 기존 제안서를 편집합니다.
스크립트를 사용할 수 없음: 수동 대체 방법을 따릅니다. 워크플로우는 프롬프트 우선입니다.

솔직한 한계

표준 보고서는 선언된 구성을 설명하며, 반드시 시행된 관행을 설명하는 것은 아닙니다. 이는 기획자를 위한 프롬프트일 뿐, 규정 준수의 증거가 아닙니다.
base_spec_sha256은 기본 명세에 대한 바이트 변경을 감지합니다. 수렴 후 보관된 제안서는 드리프트 검사에서 제외됩니다.
선택적 스크립트는 우회 가능합니다. CI와 저장소 권한이 여전히 권위적입니다.

변경 (브라운필드)