---
name: create-spec
version: 1.0.0
description: agent-spec 최초 생성, 현재 구현 스펙 작성, living spec bootstrap, 완료된 기능의 구현 스펙 신규 문서화 요청에 사용한다. 코드/계약/테스트/로드맵 근거를 바탕으로 agent-spec/index.md와 매칭 spec 문서를 생성한다.
---

# create-spec

## 목적

현재 구현된 기능의 agent-facing living spec을 새로 만든다.
스펙은 로드맵 완료 이력이나 계약 원문을 복제하지 않고, agent가 작업 전에 현재 동작과 코드 진입점을 빠르게 찾는 지도로 유지한다.

## 언제 호출할지

- 사용자가 "스펙 생성", "구현 스펙 작성", "현재 구현 문서화", "agent-spec 생성"을 요청할 때
- agent-spec을 처음 도입해 `agent-spec/index.md`와 초기 spec 문서를 만들 때
- 완료된 기능이나 활성 기능에 대응되는 현재 구현 spec 문서가 없고, 새 spec 작성이 필요한 때
- `complete-milestone` 또는 `update-spec`에서 관련 spec이 없지만 evidence가 충분해 신규 작성이 필요하다고 판단한 때

## 입력

- `mode`: `bootstrap` 또는 `targeted`. 기본값은 요청에서 추론한다. (선택)
- `spec-id`: 만들 spec id. `<area>/<spec-id>` 형식을 권장한다. (선택)
- `target-milestone`: spec 근거로 삼을 활성 또는 명시 Milestone 경로, 이름, slug. (선택)
- `source-paths`: 우선 확인할 코드, 계약, 테스트, docs 경로 목록. (선택)
- `evidence`: complete.log, SDD, 사용자 설명, 검증 결과 등 보조 근거. (선택)

## 먼저 확인할 것

- [ ] `agent-ops/rules/common/rules-agent-spec.md`를 읽는다.
- [ ] `agent-spec/` 존재 여부와 `agent-spec/index.md` 존재 여부를 확인한다.
- [ ] `agent-ops/skills/common/_templates/agent-spec/index-template.md`와 `spec-template.md`를 확인한다.
- [ ] 계약에 닿는 spec이면 `agent-contract/index.md`를 읽고 매칭 계약 문서만 읽는다.
- [ ] 로드맵 근거가 필요하면 활성 Milestone/SDD만 우선 읽고, archive는 사용자가 명시했거나 현재 스펙 배경 확인에 꼭 필요한 링크만 좁게 읽는다.

## 실행 절차

1. **범위 결정**
   - 요청을 `bootstrap` 또는 `targeted`로 분류한다.
   - `targeted`이면 spec 하나의 기능 범위와 `spec-id`를 정한다.
   - `bootstrap`이면 프로젝트 전체를 완성하려 하지 말고, 코드/계약으로 확인 가능한 핵심 축과 spec 후보 목록을 먼저 만든다.
   - `spec-id`는 소문자 영문, 숫자, 하이픈, `/`만 사용한다.

2. **근거 수집**
   - 코드, 계약, 테스트, 설정 예시, README/docs, 활성 roadmap/SDD, complete.log 순서로 현재 동작 근거를 확인한다.
   - 현재 동작은 코드와 계약으로 재확인한다.
   - 로드맵 archive 또는 agent-task archive는 일반 탐색하지 않는다.
   - 확인할 수 없는 내용은 `불명확` 또는 `확인 필요`로 둔다.

3. **agent-spec 구조 생성**
   - `agent-spec/`가 없으면 만든다.
   - `agent-spec/index.md`가 없으면 index template으로 만든다.
   - 필요한 `<area>/` 디렉터리를 만든다.
   - 기존 같은 `spec-id` 문서가 있으면 새로 만들지 말고 `update-spec` 대상이라고 보고한다.

4. **spec 문서 작성**
   - spec template의 표준 섹션 순서를 유지한다.
   - frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`를 채운다.
   - `status`는 evidence 수준에 따라 `구현됨`, `부분`, `가정`, `불명확` 중 하나로 둔다.
   - 계약 원문, proto field 전체 목록, config schema 원문은 복제하지 않고 링크한다.
   - 주요 코드 진입점과 검증 방법을 경로와 명령으로 남긴다.

5. **index 갱신**
   - `Spec Map`에 새 spec id, 상태, 읽는 조건, path, 주요 evidence를 추가하거나 보정한다.
   - 매칭 조건은 agent가 좁게 읽을 수 있도록 기능명, 코드 경로, 계약 id, 운영 표면 중심으로 쓴다.
   - 기존 행을 삭제하거나 재정렬하지 않는다. 명백히 placeholder인 `없음` 행은 첫 실제 spec 추가 시 제거할 수 있다.

6. **결과 보고**
   - 만든 spec 문서와 index 변경 내용을 보고한다.
   - 불명확하거나 후속 `update-spec`이 필요한 항목을 보고한다.

## 실행 결과 검증

- [ ] `agent-spec/index.md`가 존재하고 Spec Map에 생성한 spec이 들어 있는가
- [ ] 생성한 spec 문서가 `rules-agent-spec.md`의 표준 섹션 순서를 유지하는가
- [ ] frontmatter의 `spec_doc_type`, `spec_id`, `status`, `source_evidence`가 채워졌는가
- [ ] source evidence path가 실제 파일이거나 `path: null`인 사용자 근거인가
- [ ] 계약 원문을 복제하지 않고 `agent-contract/` 또는 코드 링크로 연결했는가
- [ ] archive를 무차별로 읽거나 과거 완료 기록을 현재 truth처럼 쓰지 않았는가
- [ ] `git diff --check`를 실행했는가
- 검증 실패 시: spec 문서와 index만 보완하고 코드 파일은 수정하지 않는다.

## 출력 형식

```markdown
## Spec 생성 완료

- 모드: <bootstrap | targeted>
- 생성/갱신 파일:
  - [index.md](agent-spec/index.md)
  - [<spec-id>.md](agent-spec/<area>/<spec-id>.md)
- 상태: <구현됨 | 부분 | 가정 | 불명확>
- 주요 evidence:
  - <path 또는 사용자 근거> - <요약>

## TODO 항목

- <확인 필요 또는 없음>
```

## 금지 사항

- agent-spec에 계약 원문, proto 전체 필드, config schema 원문을 복제하지 않는다.
- 현재 코드/계약으로 확인하지 않은 내용을 구현 사실처럼 쓰지 않는다.
- archive 전체를 훑지 않는다.
- 기존 spec이 있으면 중복 spec을 만들지 않는다.
- 사람용 공개 가이드를 agent-spec에 장황하게 작성하지 않는다.
- spec 생성과 무관한 코드 파일을 수정하지 않는다.