diff --git a/AGENTS.md b/AGENTS.md index d91426da..390f9fef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,14 +158,19 @@ Strong success criteria let you loop independently. Weak criteria ("make it work - 커밋 본문에는 `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus ` 자동 footer를 포함하지 않는다. - `git commit` 실행 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 검증한다. -## 작업 계획 문서 규칙 (docs) -- 모든 작업 시작 전에 `docs` 폴더 아래에 계획 문서를 먼저 생성하고, 해당 문서를 기준으로 구현을 진행한다. -- 연속된 하나의 작업에 대한 후속 수정/보완이라면 새 계획 문서를 만들지 말고 기존 계획 문서에 작업 항목과 검증 기록을 이어서 추가한다. -- 계획 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. +## PRD 및 계획 TASK 문서 규칙 (docs) +- PRD와 계획 TASK 문서 없이 구현하지 않는다. +- 작업 문서 작성과 구현은 반드시 `사용자 프롬프트 입력 -> PRD 문서 작성 -> 모호한 사항 사용자 인터뷰 -> 인터뷰 내용으로 PRD 보강 -> PRD 기반 계획 TASK 문서 작성 -> 계획 TASK 기반 최소 구현` 순서로 진행한다. +- PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다. +- PRD 문서는 `docs/prd/` 아래에 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성한다. +- 계획 TASK 문서는 `docs/plan-task/` 아래에 작성하고, 해당 문서를 기준으로 구현을 진행한다. +- 연속된 하나의 작업에 대한 후속 수정/보완이라면 새 PRD 또는 계획 TASK 문서를 만들지 말고 기존 문서에 요구사항, 작업 항목, 검증 기록을 이어서 추가한다. +- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md` 형식을 사용해 계획 TASK 문서와 구분한다. +- 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다. -- 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다. +- 계획 TASK 문서의 구현 항목은 기능/작업 단위로 분리해 체크박스(`- [ ]`) 목록으로 작성한다. - 구현 완료 시마다 체크박스를 `- [x]`로 갱신하고, 범위가 바뀌면 문서를 먼저 갱신한다. -- 결과 보고 시 계획 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다. +- 결과 보고 시 계획 TASK 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다. ## 에이전트 동작 원칙 - 추측하지 말고, 근거 파일을 읽고 결정한다. diff --git a/docs/agent-guides/문서유지보수.md b/docs/agent-guides/문서유지보수.md index d2addaa2..3763b015 100644 --- a/docs/agent-guides/문서유지보수.md +++ b/docs/agent-guides/문서유지보수.md @@ -1,11 +1,14 @@ # 문서 유지보수 ## 문서 유지보수 규칙 +- PRD 문서는 `docs/prd/`에 두고, 계획 TASK 문서는 `docs/plan-task/`에 둔다. +- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`, 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. +- PRD 문서는 `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다. - `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다. - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다. - `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다. - Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다. -- 연속된 하나의 작업에 대해 계획 문서가 여러 개 생기지 않도록 기존 계획 문서 재사용 여부를 먼저 확인한다. +- 연속된 하나의 작업에 대해 PRD 또는 계획 TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다. - 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다. - 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다. - 에이전트 안내 문구는 한국어 중심으로 유지한다. diff --git a/docs/agent-guides/작업절차.md b/docs/agent-guides/작업절차.md index 8484f703..63bf1c6e 100644 --- a/docs/agent-guides/작업절차.md +++ b/docs/agent-guides/작업절차.md @@ -1,8 +1,12 @@ # 작업 절차 ## 작업 절차 체크리스트 +- 변경 전: PRD와 계획 TASK 문서 없이 구현하지 않는다. +- 변경 전: 사용자 프롬프트를 받으면 먼저 `docs/prd/` 아래에 PRD 문서를 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌한다. +- 변경 전: PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰하고 PRD를 보강한다. +- 변경 전: 보강된 PRD를 바탕으로 `docs/plan-task/` 아래에 계획 TASK 문서를 작성한 뒤, 해당 문서를 기준으로 필요한 내용만 최소 구현한다. - 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다. -- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 계획 문서를 만들지 말고 기존 계획 문서를 갱신한다. +- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 PRD 또는 계획 TASK 문서를 만들지 말고 기존 문서를 갱신한다. - 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다. - 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다. - 커밋 전/후: `commit-policy` 스킬을 먼저 로드하고, `git commit` 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 커밋 메시지 규칙 준수 여부를 확인한다. diff --git a/docs/plan-task/20260513_에이전트문서작업절차개선.md b/docs/plan-task/20260513_에이전트문서작업절차개선.md new file mode 100644 index 00000000..d6c58ebf --- /dev/null +++ b/docs/plan-task/20260513_에이전트문서작업절차개선.md @@ -0,0 +1,23 @@ +# 에이전트 문서 작업 절차 개선 계획 + +## 구현 계획 +- [x] `AGENTS.md`, 연결 문서, `docs/prd/sample-prd.md`, 기존 `docs/plan-task/` 구조를 확인한다. +- [x] 이번 변경을 위한 PRD 문서를 `docs/prd/` 아래에 작성한다. +- [x] PRD/계획/TASK 필수 작성 순서와 저장 위치 규칙을 `AGENTS.md`에 반영한다. +- [x] 같은 취지의 실행 흐름을 `docs/agent-guides/작업절차.md`에 반영한다. +- [x] 문서 유지보수 규칙을 `docs/agent-guides/문서유지보수.md`에 반영한다. +- [x] 문서 진단과 검증 결과를 기록한다. + +## 검증 계획 +- [x] 변경한 Markdown 문서에 대해 `lsp_diagnostics`를 실행한다. +- [x] 문서 변경 후 `./gradlew tasks --all`로 Gradle 명령 유효성을 확인한다. + +## 검증 기록 +- 1차 PRD/계획 작성 + - 무엇을: 사용자 요청에 따라 구현 전 PRD와 계획 TASK 문서를 먼저 작성했다. + - 왜: 새 규칙 자체가 PRD와 계획 TASK 문서 없이 구현하지 않는 흐름을 요구하므로, 이번 문서 변경에도 동일한 절차를 적용하기 위해서다. + - 어떻게: `docs/prd/sample-prd.md`에서 필요한 섹션을 발췌해 `docs/prd/20260513_에이전트문서작업절차개선_prd.md`를 작성하고, 구현 체크리스트를 `docs/plan-task/20260513_에이전트문서작업절차개선.md`에 정리했다. +- 2차 문서 반영 및 검증 + - 무엇을: `AGENTS.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`에 PRD와 계획 TASK 문서 작성 순서, 저장 위치, 파일명 규칙, 사용자 인터뷰 규칙을 반영했다. + - 왜: 에이전트가 구현 전에 요구사항을 PRD로 고정하고, 모호한 사항을 사용자 인터뷰로 해소한 뒤 계획 TASK 문서를 기준으로 최소 구현하도록 문서 간 규칙을 일치시키기 위해서다. + - 어떻게: 변경한 Markdown 문서 5개에 대해 `lsp_diagnostics`를 실행해 모두 `No diagnostics found`를 확인했고, `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL in 13s`를 확인했다. diff --git a/docs/prd/20260513_에이전트문서작업절차개선_prd.md b/docs/prd/20260513_에이전트문서작업절차개선_prd.md new file mode 100644 index 00000000..7bf506d0 --- /dev/null +++ b/docs/prd/20260513_에이전트문서작업절차개선_prd.md @@ -0,0 +1,58 @@ +# PRD: 에이전트 문서 작업 절차 개선 + +## 1. Overview +에이전트가 구현 전에 PRD와 계획 TASK 문서를 순서대로 작성하고, 필요한 경우 사용자 인터뷰로 요구사항을 확정하도록 작업 절차 문서를 정리한다. + +--- + +## 2. Problem +- 기존 `AGENTS.md`는 작업 계획 문서 작성만 요구하고 있어 PRD 작성과 사용자 인터뷰 흐름이 명확하지 않다. +- 계획 문서 저장 위치가 `docs`로 넓게 표현되어 있어 현재 저장 구조인 `docs/plan-task/`와 완전히 일치하지 않는다. +- PRD 문서 작성 시 `docs/prd/sample-prd.md`에서 필요한 섹션을 발췌한다는 기준이 연결 문서에 명시되어 있지 않다. + +--- + +## 3. Goals +- 구현 전 필수 문서 순서를 `PRD -> 계획 TASK -> 최소 구현`으로 고정한다. +- PRD 문서 저장 위치를 `docs/prd/`, 계획 TASK 문서 저장 위치를 `docs/plan-task/`로 명확히 한다. +- PRD 파일명은 기존 계획 문서 파일명 규칙을 따르되 계획 문서와 구분되도록 한다. +- 애매한 요구사항은 PRD 단계에서 사용자 인터뷰를 반복해 해소하도록 명시한다. + +--- + +## 4. Non-Goals +- 기존 작업 계획 문서들의 파일명을 일괄 변경하지 않는다. +- `sample-prd.md` 템플릿 자체를 변경하지 않는다. +- 코드 구현 방식이나 테스트 스타일 규칙은 이번 변경 범위에 포함하지 않는다. + +--- + +## 7. Core Features + +### 문서 작성 순서 고정 + +#### Requirements +- 사용자가 작업 프롬프트를 입력하면 먼저 PRD 문서를 작성한다. +- 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 해소될 때까지 사용자와 인터뷰한다. +- 인터뷰 내용을 바탕으로 PRD 문서를 보강한다. +- PRD를 바탕으로 계획 TASK 문서를 작성한다. +- 계획 TASK 문서를 바탕으로 필요한 내용만 최소 구현한다. + +### 문서 저장 위치와 파일명 규칙 + +#### Requirements +- PRD 문서는 `docs/prd/`에 작성한다. +- 계획 TASK 문서는 `docs/plan-task/`에 작성한다. +- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`처럼 기존 계획 문서 규칙과 구분되는 접미사를 사용한다. +- 계획 TASK 문서 파일명은 기존 `[날짜]_구현할내용한글.md` 규칙을 유지한다. + +--- + +## 9. Technical Constraints +- `AGENTS.md`와 `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`의 표현을 일치시킨다. +- 기존 문서 구조와 한국어 안내 원칙을 유지한다. + +--- + +## 11. Open Questions +- 없음. 사용자 요청에서 필수 흐름과 저장 위치가 구체적으로 지정되었다.