alt/agent-ops/skills/common/update-spec/SKILL.md

name	version	description
update-spec	1.0.0	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. 영향 판정

   • 현재 동작, 범위, 주요 흐름, 책임 경계, 계약 링크, 코드 진입점, 설정/데이터/이벤트, 검증, 한계 중 바뀐 항목을 식별한다.
   • 변경이 테스트 fixture, 내부 리팩터링, 문구 정리처럼 현재 구현 spec에 영향을 주지 않으면 Spec update not needed: <사유>를 남긴다.
   • 판단 불가이면 spec을 추정 갱신하지 않고 Spec blocked: <필요 evidence>로 보고한다.

4. 문서 갱신

   • mode=check-only이면 쓰지 않고 갱신 후보만 보고한다.
   • 영향이 있는 spec 문서만 수정한다.
   • frontmatter status와 source_evidence를 현재 evidence에 맞게 보강한다.
   • 표준 섹션 순서를 유지한다.
   • 계약 원문을 복제하지 않고 링크만 보강한다.
   • 변경 기록에 날짜, 변경 근거, 관련 Milestone/complete.log/코드 경로를 남긴다.

5. index 동기화

   • spec 상태, 읽는 조건, path, 주요 evidence가 바뀌었으면 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가 유지되는가
• index의 Spec Map이 갱신한 spec 상태와 일치하는가
• 계약 원문을 복제하지 않았는가
• 갱신/불필요/create 필요/차단 중 하나의 결과가 명확한가
• complete-milestone에서 호출된 경우 Milestone 완료 리뷰에 남길 spec sync 문구를 제공했는가
• git diff --check를 실행했는가
• 검증 실패 시: roadmap이나 코드 파일을 수정하지 말고 spec 갱신 실패 사유를 보고한다.

출력 형식

## 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 문구만으로 현재 동작을 단정하지 않는다.