appsok/agent-ops/skills/common/create-spec/SKILL.md

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

create-spec

목적

현재 구현된 기능의 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 수준에 따라 구현됨, 부분, 가정, 불명확 중 하나로 둔다.
   • 기능 목록을 목적 다음에 바로 둔다.
   • 기능 목록은 기능과 설명 중심으로 작성한다. 기능별 상태 칼럼은 기본 생성하지 않는다.
   • 주요 흐름은 Mermaid sequenceDiagram 또는 flowchart를 우선 고려한다. 단순 기능은 짧은 목록으로 둔다.
   • 책임 경계는 기능 이해에 필요한 최소 수준만 적고, 도메인별 코드 배치나 금지 사항은 domain rule로 넘긴다.
   • 계약 원문, proto field 전체 목록, config schema 원문은 복제하지 않고 링크한다.
   • 코드 진입점 섹션은 만들지 않는다. 코드 근거는 source_evidence에 남긴다.
   • 검증 방법은 실행 가능한 명령 또는 확인 기준으로 남긴다.

5. index 갱신

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

6. 결과 보고

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

실행 결과 검증

• agent-spec/index.md가 존재하고 Spec Map에 생성한 spec이 들어 있는가
• 생성한 spec 문서가 rules-agent-spec.md의 기본 섹션 기준을 따르는가
• 기능 목록이 기능/설명 중심이며 불필요한 상태 칼럼이나 과한 상세 설명을 만들지 않았는가
• 코드 진입점, 패키지 배치, 도메인별 금지 사항을 spec 본문에 반복하지 않았는가
• frontmatter의 spec_doc_type, spec_id, status, source_evidence가 채워졌는가
• source evidence path가 실제 파일이거나 path: null인 사용자 근거인가
• 계약 원문을 복제하지 않고 agent-contract/ 또는 코드 링크로 연결했는가
• archive를 무차별로 읽거나 과거 완료 기록을 현재 truth처럼 쓰지 않았는가
• git diff --check를 실행했는가
• 검증 실패 시: spec 문서와 index만 보완하고 코드 파일은 수정하지 않는다.

출력 형식

## Spec 생성 완료

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

## TODO 항목

- <확인 필요 또는 없음>

금지 사항

• agent-spec에 계약 원문, proto 전체 필드, config schema 원문을 복제하지 않는다.
• 현재 코드/계약으로 확인하지 않은 내용을 구현 사실처럼 쓰지 않는다.
• archive 전체를 훑지 않는다.
• 기존 spec이 있으면 중복 spec을 만들지 않는다.
• 코드 진입점, 구현 배치, 도메인 간 상세 책임 경계, 유지할 패턴, 금지 사항을 domain rule 대신 agent-spec에 길게 쓰지 않는다.
• 사람용 공개 가이드를 agent-spec에 장황하게 작성하지 않는다.
• spec 생성과 무관한 코드 파일을 수정하지 않는다.