100 lines
5.6 KiB
Markdown
100 lines
5.6 KiB
Markdown
# agent-spec 규칙
|
|
|
|
`agent-spec/`가 있는 프로젝트 또는 agent-spec 생성, 갱신, 마일스톤 종료 검토 요청에서 적용한다.
|
|
|
|
## 목적
|
|
|
|
`agent-spec/`는 AI agent가 현재 구현된 기능의 동작, 책임 경계, 코드 진입점, 계약 링크, 검증 방법을 빠르게 파악하기 위한 living spec 저장소다.
|
|
로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다.
|
|
|
|
## 기본 구조
|
|
|
|
```text
|
|
agent-spec/
|
|
index.md
|
|
archive/
|
|
<area>/
|
|
<spec-id>.log
|
|
<area>/
|
|
<spec-id>.md
|
|
```
|
|
|
|
- `index.md`는 현재 스펙 목록과 읽기 라우팅 source of truth다.
|
|
- `<area>/<spec-id>.md`는 현재 구현 스펙 문서다.
|
|
- `archive/**`는 폐기되거나 대체된 과거 스펙 스냅샷이다.
|
|
- `<area>`와 `<spec-id>`는 소문자 영문, 숫자, 하이픈만 사용한다.
|
|
|
|
## Source of Truth
|
|
|
|
- `agent-spec/**`는 현재 구현 지도를 제공하지만 최종 truth는 코드, `agent-contract/`, 테스트, 설정 예시다.
|
|
- API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약 원문은 `agent-contract/`에 두고 agent-spec에는 링크와 사용 맥락만 남긴다.
|
|
- SDD는 구현 전 설계 게이트다. agent-spec은 구현 후 현재 상태를 설명한다.
|
|
- 로드맵과 complete.log는 완료 근거와 변경 힌트로 사용한다. 현재 동작은 코드와 계약으로 재확인한다.
|
|
- 사람용 최신 가이드는 `docs/`에 둔다. agent-spec은 agent 작업 문맥을 우선한다.
|
|
|
|
## Frontmatter Schema
|
|
|
|
- 활성 Markdown 문서는 YAML frontmatter를 둔다.
|
|
- `spec_doc_type`은 `index`, `spec`, `archive-log` 중 하나다.
|
|
- spec 문서는 `spec_id`, `status`, `source_evidence`를 둔다.
|
|
- 활성 spec 문서의 `status` 값은 `구현됨`, `부분`, `가정`, `불명확` 중 하나다.
|
|
- archive log의 `status` 값은 `폐기됨`을 사용할 수 있다.
|
|
- `구현됨`은 코드/계약/테스트 evidence로 현재 동작이 확인된 상태다.
|
|
- `부분`은 핵심 경로는 확인됐지만 일부 흐름, 설정, 검증, 한계가 남은 상태다.
|
|
- `가정`은 사용자 입력 또는 제한된 evidence를 바탕으로 임시 정리한 상태다.
|
|
- `불명확`은 코드와 계약 기준으로 현재 동작을 확정할 수 없는 상태다.
|
|
- `폐기됨`은 활성 spec 문서에 두지 않는다.
|
|
- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다.
|
|
- `source_evidence.type`은 `code`, `contract`, `roadmap`, `sdd`, `test`, `docs`, `complete-log`, `user` 중 하나다.
|
|
- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다.
|
|
|
|
## 읽기 규칙
|
|
|
|
- 일반 작업마다 `agent-spec/`를 읽지 않는다.
|
|
- 기존 기능의 현재 동작, 책임 경계, 코드 진입점, 계약 링크가 필요한 작업에서만 세션 1회 `agent-spec/index.md`를 읽는다.
|
|
- `index.md`에서 매칭되는 spec 문서만 읽는다.
|
|
- 매칭 spec이 없으면 스펙이 없다고 보고하고 코드, 계약, 테스트에서 직접 확인한다. 추측으로 spec 내용을 만들지 않는다.
|
|
- spec 문서가 코드/계약과 충돌하면 코드/계약을 우선하고 `update-spec` 필요를 보고한다.
|
|
- API, wire protocol, runtime call, event/config schema, 프로세스 간 요청/응답 계약에 닿으면 `agent-contract/index.md`의 규칙에 따라 매칭 계약 문서도 읽는다.
|
|
- `agent-spec/archive/**`는 일반 작업에서 읽지 않는다.
|
|
- 예외: 사용자가 과거 스펙 확인, 복원, 비교, 특정 archive 경로 확인을 요청한 경우에만 필요한 archive 문서만 좁게 읽는다.
|
|
|
|
## 생성/갱신 흐름
|
|
|
|
- agent-spec 최초 도입, 현재 구현 스펙 신규 작성, 전체 bootstrap 작성은 `create-spec`을 사용한다.
|
|
- 기존 spec을 코드/계약/테스트/완료 근거에 맞게 갱신하는 작업은 `update-spec`을 사용한다.
|
|
- 마일스톤 종료 검토에서는 `complete-milestone`이 `update-spec`을 필수 gate로 실행한다.
|
|
- `agent-spec/`가 없으면 `complete-milestone`의 spec gate는 `skipped-no-agent-spec`으로 기록할 수 있다.
|
|
- `agent-spec/`가 있으면 `complete-milestone`은 `Spec updated` 또는 `Spec update not needed`를 완료 리뷰에 남긴 뒤에만 Milestone 완료/archive를 진행한다.
|
|
- `Spec blocked` 또는 `create-spec needed`이면 Milestone 완료/archive를 진행하지 않는다.
|
|
- 새 스펙 작성이나 갱신은 현재 코드/계약/테스트 evidence를 우선하고, 완료된 roadmap archive는 사용자가 요청했거나 현재 스펙의 배경 확인이 꼭 필요한 경우에만 좁게 읽는다.
|
|
|
|
## 문서 작성 기준
|
|
|
|
- 현재형으로 작성한다.
|
|
- 과거 작업 일지, 설계 논쟁 전문, 완료된 roadmap task 전체 복사, 함수 단위 코드 설명을 넣지 않는다.
|
|
- 스펙 본문은 기능 단위의 작동 지도여야 한다.
|
|
- 계약 원문, proto field 전체 목록, config schema 원문을 복제하지 말고 `agent-contract/` 또는 코드 경로를 링크한다.
|
|
- 불확실한 내용은 단정하지 말고 `불명확` 또는 `확인 필요`로 남긴다.
|
|
- spec 갱신이 필요 없으면 `Spec update not needed: <사유>`를 결과 보고나 Milestone 완료 리뷰에 남긴다.
|
|
|
|
## 표준 섹션
|
|
|
|
spec 문서는 아래 섹션 순서를 유지한다.
|
|
|
|
1. `목적`
|
|
2. `현재 동작`
|
|
3. `범위`
|
|
4. `주요 흐름`
|
|
5. `책임 경계`
|
|
6. `계약`
|
|
7. `코드 진입점`
|
|
8. `설정/데이터/이벤트`
|
|
9. `검증`
|
|
10. `한계와 주의사항`
|
|
11. `변경 기록`
|
|
|
|
## 템플릿
|
|
|
|
- `index.md`: `agent-ops/skills/common/_templates/agent-spec/index-template.md`
|
|
- spec 문서: `agent-ops/skills/common/_templates/agent-spec/spec-template.md`
|