docs(ai-character): OpenAPI 계약 반영

docs/agent-guide/documentation.md

@@ -3,6 +3,8 @@
 - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
 - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
 - PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
+- 기능별 API Contract도 같은 디렉터리에 두고 PRD·계획에서 실제 파일명을 링크한다. 계약 형식은 Markdown에 한정하지 않으며 OpenAPI JSON이면 `<이름>.openapi.json`처럼 형식이 드러나는 파일명을 사용한다.
+- 기능별 설계 결정은 `prd.md`의 요구사항·결정 기록에, 실행 절차는 `plan-task.md`의 Task·검증 기록에 통합한다. 같은 기능을 위한 별도 spec/plan 디렉터리를 `docs/` 아래에 병렬로 만들지 않는다.
 - 공통 샘플 문서는 `docs/sample/`에 두며 기능별 문서 디렉터리에 복제하지 않는다.
 - PRD를 작성·변경할 때는 [PRD 작성 및 유지보수 규칙](./prd.md)과 [PRD 샘플](../sample/sample-prd.md)을 따른다.
 - 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다.

docs/agent-guide/goal-plan.md

@@ -3,7 +3,7 @@
 ## 1. 적용 시점
 
 - 사용자가 goal 기능으로 구현을 진행하거나, goal에 적합한 `plan-task.md` 작성·보완을 요청하면 이 문서를 따른다.
-- 구현 전에 [PRD 작성 및 유지보수 규칙](./prd.md), 대상 기능의 `prd.md`, `api-contract.md`, 기존 `plan-task.md`, 관련 코드·test와 저장소 가이드를 읽는다.
+- 구현 전에 [PRD 작성 및 유지보수 규칙](./prd.md), 대상 기능의 `prd.md`, 실제 API Contract 파일, 기존 `plan-task.md`, 관련 코드·test와 저장소 가이드를 읽는다.
 - 계획 작성 요청은 문서 변경 범위다. 사용자가 구현까지 요청하지 않았다면 애플리케이션 코드와 설정을 변경하지 않는다.
 
 ## 2. 기준 템플릿과 위치

docs/agent-guide/prd.md

@@ -27,7 +27,7 @@
 ## 4. 문서 간 추적
 
 - 제품 결정과 사용자 요구는 PRD가 소유한다.
-- request/response/error와 endpoint 세부 계약은 `api-contract.md`가 소유한다.
+- request/response/error와 endpoint 세부 계약은 대상 기능의 실제 API Contract 파일(Markdown 또는 OpenAPI)이 소유한다.
 - 구현 순서, Files, Interfaces, Task/Goal과 완료 증거는 `plan-task.md`가 소유한다.
 - 모든 확정 요구사항을 API Contract section 또는 명시적인 contract 불필요 판정, 하나 이상의 Phase/Goal, 자동·수동 검증으로 연결한다.
 - Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 별도 외부 의존 ID로 관리한다.
@@ -47,6 +47,6 @@
 - 사용자·권한·핵심 흐름과 라우팅 경계가 명확하다.
 - 모든 요구사항 ID가 고유하고 상태·수용 기준을 가진다.
 - 미결·외부 의존·제외 항목에 다음 행동과 담당 주체가 있다.
-- API endpoint와 payload 규칙이 `api-contract.md`로 추적된다.
+- API endpoint와 payload 규칙이 대상 API Contract 파일로 추적된다.
 - 기능·UX·보안·성능 성공 기준이 자동 또는 수동 검증 가능한 표현이다.
 - placeholder, 근거 없는 최대값과 추정 계약이 없다.

docs/agent-guide/review.md

@@ -8,7 +8,7 @@
 
 ## 2. 기준 문서와 템플릿
 
-- 리뷰 전에 대상 기능 디렉터리의 `prd.md`, `api-contract.md`, `plan-task.md`와 관련 구현·test를 읽는다.
+- 리뷰 전에 대상 기능 디렉터리의 `prd.md`, 실제 API Contract 파일, `plan-task.md`와 관련 구현·test를 읽는다.
 - 대상 `prd.md`와 `plan-task.md`가 있는 기능 문서 디렉터리 아래 `reviews/`를 만들고 모든 리뷰 문서를 그 안에 둔다.
 - 리뷰 문서를 기능 문서 디렉터리 바로 아래나 단수형 `review/`에 두지 않는다. 여러 Phase·Task 리뷰가 생겨도 같은 `reviews/`에 누적한다.
 - [코드 리뷰 보고서 샘플](../sample/sample-review.md)을 원본 템플릿으로 사용하고, section·필드·상태 의미를 임의로 축소하지 않는다.