124 lines
7.7 KiB
Markdown
124 lines
7.7 KiB
Markdown
---
|
|
name: update-spec
|
|
version: 1.0.0
|
|
description: agent-spec 갱신, 구현 스펙 업데이트, 완료 기능 스펙 반영, 코드/계약/테스트 변경 후 living spec 동기화 요청에 사용한다. agent-spec/index.md에서 관련 spec을 찾아 현재 코드와 계약 기준으로 갱신하고 Spec updated, Spec update not needed, create-spec needed, Spec blocked 결과를 남긴다.
|
|
---
|
|
|
|
# update-spec
|
|
|
|
## 목적
|
|
|
|
기존 agent-spec 문서를 현재 코드, 계약, 테스트, 완료 evidence에 맞게 갱신한다.
|
|
이 스킬은 spec 문서만 책임지며 roadmap 상태 전환, Milestone archive, 코드 구현 계획 생성을 수행하지 않는다.
|
|
|
|
## 언제 호출할지
|
|
|
|
- 사용자가 "스펙 업데이트", "구현 스펙 갱신", "완료 기능 스펙 반영", "agent-spec 갱신"을 요청할 때
|
|
- 코드, 계약, config, event, runtime flow, 테스트가 바뀌어 현재 구현 spec이 달라질 수 있을 때
|
|
- `complete-milestone`이 Milestone 종료 전에 spec sync gate를 수행할 때
|
|
- `create-spec` 이후 불명확/부분 상태의 spec을 추가 evidence로 보강할 때
|
|
|
|
## 입력
|
|
|
|
- `target-spec`: 갱신할 spec id 또는 문서 경로. 없으면 index와 변경 근거에서 추론한다. (선택)
|
|
- `target-milestone`: spec 갱신 근거가 되는 Milestone 경로, 이름, slug. (선택)
|
|
- `changed-files`: spec 영향 판단에 사용할 코드/계약/테스트 파일 목록. (선택)
|
|
- `complete-log`: 완료 근거로 사용할 `complete.log` 경로. (선택)
|
|
- `mode`: `update` 또는 `check-only`. 기본값은 `update`다. (선택)
|
|
|
|
## 먼저 확인할 것
|
|
|
|
- [ ] `agent-ops/rules/common/rules-agent-spec.md`를 읽는다.
|
|
- [ ] `agent-spec/index.md`가 있는지 확인한다. 없으면 `create-spec` 필요 또는 `skipped-no-agent-spec`으로 보고한다.
|
|
- [ ] 매칭 spec 문서만 읽는다.
|
|
- [ ] 계약에 닿는 변경이면 `agent-contract/index.md`를 읽고 매칭 계약 문서만 읽는다.
|
|
- [ ] Milestone 또는 complete.log 근거가 있으면 해당 활성 Milestone, SDD gate, complete.log의 관련 섹션만 확인한다.
|
|
|
|
## 실행 절차
|
|
|
|
1. **대상 spec 확정**
|
|
- `target-spec`이 있으면 해당 문서가 활성 `agent-spec/**` 아래에 정확히 존재하는지 확인한다.
|
|
- `target-spec`이 없으면 `agent-spec/index.md`의 읽는 조건, spec id, path, evidence와 `changed-files`/Milestone/complete.log를 비교한다.
|
|
- 매칭 spec이 없고 구현 스펙 영향이 명확하면 `create-spec` 필요로 보고한다. 이 스킬에서 새 spec 문서를 직접 만들지 않는다.
|
|
- 매칭 spec이 없고 변경이 spec 대상이 아니면 `Spec update not needed`로 보고한다.
|
|
- 둘 이상의 spec이 매칭되면 모두 갱신 대상 후보로 두되, 각 spec별 영향 근거를 분리한다.
|
|
|
|
2. **현재 구현 재확인**
|
|
- spec 본문만 믿지 말고 관련 코드, 계약, 테스트, 설정 예시를 다시 확인한다.
|
|
- complete.log와 roadmap은 변경 근거로 쓰되 현재 동작은 코드/계약으로 검증한다.
|
|
- SDD가 있으면 acceptance/evidence가 현재 spec과 어긋나는지 확인한다.
|
|
- spec과 코드/계약이 충돌하면 코드/계약을 우선하고 spec을 수정한다.
|
|
|
|
3. **영향 판정**
|
|
- 기능 목록, 범위, 주요 흐름, 계약 링크, 설정/데이터/이벤트, 검증, 한계 중 바뀐 항목을 식별한다.
|
|
- 기능 이해에 필요한 최소 책임 설명이 바뀐 경우만 spec에 반영한다.
|
|
- 코드 배치, 구현 진입점, 유지할 패턴, 금지 사항 변경은 domain rule 갱신 대상으로 본다.
|
|
- 변경이 테스트 fixture, 내부 리팩터링, 문구 정리처럼 현재 구현 spec에 영향을 주지 않으면 `Spec update not needed: <사유>`를 남긴다.
|
|
- 판단 불가이면 spec을 추정 갱신하지 않고 `Spec blocked: <필요 evidence>`로 보고한다.
|
|
|
|
4. **문서 갱신**
|
|
- `mode=check-only`이면 쓰지 않고 갱신 후보만 보고한다.
|
|
- 영향이 있는 spec 문서만 수정한다.
|
|
- frontmatter `status`와 `source_evidence`를 현재 evidence에 맞게 보강한다.
|
|
- `rules-agent-spec.md`의 기본 섹션 기준을 따른다.
|
|
- 기능 목록은 `기능`과 `설명` 중심으로 유지한다. 기능별 `상태` 칼럼은 기본 추가하지 않는다.
|
|
- `주요 흐름`은 긴 텍스트보다 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다.
|
|
- `코드 진입점` 섹션은 추가하지 않는다. 기존 spec에 있으면 현재 기준에 맞춰 제거하거나 `source_evidence`로 옮긴다.
|
|
- 계약 원문을 복제하지 않고 링크만 보강한다.
|
|
- 변경 기록에 날짜, 변경 근거, 관련 Milestone/complete.log/코드 경로를 남긴다.
|
|
|
|
5. **index 동기화**
|
|
- spec 상태, 읽는 조건, path, 주요 근거가 바뀌었으면 `agent-spec/index.md`의 Spec Map을 갱신한다.
|
|
- 새 spec 문서가 필요하면 `create-spec` 대상으로 보고하고 index를 추정 갱신하지 않는다.
|
|
- 폐기된 spec은 활성 문서에 남기지 않고 archive log로 이동할 후보로 보고한다. 명시 요청 없이 archive 이동하지 않는다.
|
|
|
|
6. **결과 분류**
|
|
- 갱신한 문서가 있으면 `Spec updated`로 보고한다.
|
|
- 영향 없음이 확인되면 `Spec update not needed: <사유>`로 보고한다.
|
|
- 매칭 spec이 없고 신규 작성이 필요하면 `create-spec needed: <사유>`로 보고한다.
|
|
- evidence 부족, 대상 모호, 사용자 결정 필요이면 `Spec blocked: <사유>`로 보고한다.
|
|
|
|
## 실행 결과 검증
|
|
|
|
- [ ] `agent-spec/index.md`에서 관련 spec만 읽었는가
|
|
- [ ] 코드/계약/테스트 기준으로 현재 동작을 재확인했는가
|
|
- [ ] spec 문서의 기본 섹션 기준과 frontmatter가 유지되는가
|
|
- [ ] 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
|
|
- [ ] 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
|
|
- [ ] index의 Spec Map이 갱신한 spec 상태와 일치하는가
|
|
- [ ] 계약 원문을 복제하지 않았는가
|
|
- [ ] 갱신/불필요/create 필요/차단 중 하나의 결과가 명확한가
|
|
- [ ] `complete-milestone`에서 호출된 경우 Milestone 완료 리뷰에 남길 spec sync 문구를 제공했는가
|
|
- [ ] `git diff --check`를 실행했는가
|
|
- 검증 실패 시: roadmap이나 코드 파일을 수정하지 말고 spec 갱신 실패 사유를 보고한다.
|
|
|
|
## 출력 형식
|
|
|
|
```markdown
|
|
## Spec 동기화 결과
|
|
|
|
- 결과: <Spec updated | Spec update not needed | create-spec needed | Spec blocked | skipped-no-agent-spec>
|
|
- 대상 spec:
|
|
- <없음 | [spec-id](agent-spec/<area>/<spec-id>.md)>
|
|
- 수정 파일:
|
|
- <없음 | [index.md](agent-spec/index.md) | [spec](agent-spec/<area>/<spec-id>.md)>
|
|
- 근거:
|
|
- <코드/계약/테스트/complete.log/Milestone 요약>
|
|
- Milestone 완료 리뷰 문구:
|
|
- `Spec sync: <완료 | 해당 없음 | create-spec 필요: 사유 | 차단: 사유>`
|
|
|
|
## TODO 항목
|
|
|
|
- <남은 확인 필요 또는 없음>
|
|
```
|
|
|
|
## 금지 사항
|
|
|
|
- roadmap 상태 전환이나 archive 이동을 수행하지 않는다.
|
|
- 새 spec 문서를 생성하지 않는다. 신규 작성이 필요하면 `create-spec`으로 넘긴다.
|
|
- 코드 구현이나 테스트 코드를 수정하지 않는다.
|
|
- spec과 코드가 충돌할 때 spec을 그대로 신뢰하지 않는다.
|
|
- 매칭되지 않는 spec을 광범위하게 읽거나 전부 갱신하지 않는다.
|
|
- archive spec을 명시 요청 없이 읽거나 갱신하지 않는다.
|
|
- complete.log나 roadmap 문구만으로 현재 동작을 단정하지 않는다.
|
|
- 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.
|