agent-spec 규칙

agent-spec/가 있는 프로젝트 또는 agent-spec 생성, 갱신, 마일스톤 종료 검토 요청에서 적용한다.

목적

agent-spec/는 사람과 AI agent가 현재 구현된 기능 목록, 동작 흐름, 계약 링크, 검증 방법을 함께 파악하기 위한 living spec 저장소다. 로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다.

agent-spec/
  index.md
  archive/
    <area>/
      <spec-id>.log
  <area>/
    <spec-id>.md

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은 기능 파악과 작업 문맥을 우선한다.

활성 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에 의미가 없는 섹션은 만들지 않는다.

책임 경계가 기능 이해에 꼭 필요하면 별도 섹션으로 짧게 둘 수 있다. 이때 domain rule의 구성 요소, 코드 배치, 금지 사항을 반복하지 않는다.