108 lines
7.2 KiB
Markdown
108 lines
7.2 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에는 링크와 사용 맥락만 남긴다.
|
|
- 코드 배치, 주요 구성 요소, 구현 진입점, 도메인 간 책임 경계, 유지할 패턴, 금지 사항은 domain rule에 둔다.
|
|
- agent-spec에는 기능 이해에 필요한 최소 경계만 적고, 코딩할 때 따라야 하는 경계 규칙을 반복하지 않는다.
|
|
- SDD는 구현 전 설계 게이트다. agent-spec은 구현 후 현재 상태를 설명한다.
|
|
- 로드맵과 complete.log는 완료 근거와 변경 힌트로 사용한다. 현재 동작은 코드와 계약으로 재확인한다.
|
|
- 사람용 최신 가이드는 `docs/`에 둔다. agent-spec은 기능 파악과 작업 문맥을 우선한다.
|
|
|
|
## 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` 필요를 보고한다.
|
|
- 코드 배치, 구현 위치, 패턴, 금지 사항, 도메인 간 상세 책임 경계가 필요하면 프로젝트 규칙의 도메인 매핑에 따라 domain rule을 읽는다.
|
|
- 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 전체 복사, 함수 단위 코드 설명을 넣지 않는다.
|
|
- 스펙 본문은 기능 단위의 작동 지도여야 한다. 먼저 기능 목록을 두고, 필요한 흐름만 뒤에 보강한다.
|
|
- 기능 목록은 `기능`과 `설명` 중심으로 작성한다. 활성 spec은 구현된 기능만 기록하므로 기능별 `상태` 칼럼을 기본으로 두지 않는다.
|
|
- 기능별 부분 지원, 조건부 동작, 한계는 설명 또는 `한계와 주의사항`에 짧게 적는다.
|
|
- 주요 흐름은 텍스트만 길게 나열하지 말고 Mermaid `sequenceDiagram` 또는 `flowchart`를 우선 고려한다. 단순 기능은 짧은 목록으로 충분하다.
|
|
- 책임 경계는 기능 오해를 막는 최소 수준만 허용한다. 패키지 배치, 구현 진입점, 유지할 패턴, 금지 사항은 domain rule에 둔다.
|
|
- `코드 진입점` 섹션은 기본 섹션으로 두지 않는다. 필요한 코드 근거는 frontmatter `source_evidence`와 domain rule로 좁힌다.
|
|
- 계약 원문, proto field 전체 목록, config schema 원문을 복제하지 말고 `agent-contract/` 또는 코드 경로를 링크한다.
|
|
- 불확실한 내용은 단정하지 말고 `불명확` 또는 `확인 필요`로 남긴다.
|
|
- spec 갱신이 필요 없으면 `Spec update not needed: <사유>`를 결과 보고나 Milestone 완료 리뷰에 남긴다.
|
|
|
|
## 기본 섹션
|
|
|
|
spec 문서는 아래 섹션을 기본 순서로 작성한다. 해당 spec에 의미가 없는 섹션은 만들지 않는다.
|
|
|
|
1. `목적`
|
|
2. `기능 목록`
|
|
3. `범위`
|
|
4. `주요 흐름`
|
|
5. `계약`
|
|
6. `설정/데이터/이벤트`
|
|
7. `검증`
|
|
8. `한계와 주의사항`
|
|
9. `변경 기록`
|
|
|
|
`책임 경계`가 기능 이해에 꼭 필요하면 별도 섹션으로 짧게 둘 수 있다. 이때 domain rule의 구성 요소, 코드 배치, 금지 사항을 반복하지 않는다.
|
|
|
|
## 템플릿
|
|
|
|
- `index.md`: `agent-ops/skills/common/_templates/agent-spec/index-template.md`
|
|
- spec 문서: `agent-ops/skills/common/_templates/agent-spec/spec-template.md`
|