klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(agent): 에이전트 문서 규칙을 정리한다

Browse Source
This commit is contained in:
Klaus
2026-05-29 13:58:54 +09:00
parent ddac78a666
commit b07f2d9646
9 changed files with 132 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
.opencode/commands/commit.md
View File

@@ -1,22 +0,0 @@
---
description: commit-policy 스킬을 로드해 커밋 메시지 생성과 전후 검증을 수행한다
agent: build
subtask: true
---
작업 목표:
현재 변경사항을 안전하게 커밋한다.
필수 시작 단계:
1. `skill` 도구로 `commit-policy` 스킬을 먼저 로드한다.
- `skill({ name: "commit-policy" })`
실행 단계:
1. 로드한 `commit-policy` 스킬의 Hard Requirements와 Execution Flow를 그대로 수행한다.
2. `AGENTS.md`의 최소 정책(형식/한글 description/검증 스크립트)을 항상 만족한다.
3. `$ARGUMENTS`가 있으면 scope 또는 description 의도에 반영하되, 스킬 규칙과 형식을 깨지 않는다.
4. 가능하면 메시지 파일을 검증한 뒤 같은 파일을 `git commit -F`에 전달해 검증을 통과한 메시지를 그대로 사용하고, `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 라인이 본문에 추가되지 않도록 확인한다.
5. 마지막에 실행 명령과 pre-check/post-check PASS/FAIL 핵심 결과를 간단히 보고한다.
추가 사용자 의도:
$ARGUMENTS

49
.opencode/skills/commit-policy/SKILL.md
View File

@@ -1,49 +0,0 @@
---
name: commit-policy
description: Apply this skill for any git commit task in this repository. It enforces commit message format and validation flow defined in AGENTS.md and work/scripts/check-commit-message-rules.sh, including pre-commit and post-commit verification.
---
# Commit Policy Skill
Use this workflow whenever the task includes creating a commit.
## Required References
- `@AGENTS.md`
- `@work/scripts/check-commit-message-rules.sh`
## Hard Requirements
1. Use commit subject format: `<type>(scope): <description>`.
2. `type` must be lowercase (for example `feat`, `fix`, `chore`, `docs`, `refactor`, `test`).
3. `description` must include Korean text and stay concise in imperative present tone.
4. Optional footer must use `Refs: #123` or `Refs: #123, #456` format.
5. Never commit secret files (`.env`, key/token/secret credential files).
6. Never bypass hooks with `--no-verify`.
7. Never include `Ultraworked with [Sisyphus]...` or `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` in the commit body.
## Execution Flow
1. Inspect context with:
- `git status`
- `git diff --cached`
- `git diff`
- `git log -5 --oneline`
2. Stage commit target files only. Exclude suspicious secret-bearing files.
3. Draft commit message from the change intent (focus on why, not only what).
4. Run pre-commit validation with the full draft message:
- `./work/scripts/check-commit-message-rules.sh --message "<full message>"`
5. If validation fails, revise message and re-run until PASS.
6. Prefer validating a message file with `./work/scripts/check-commit-message-rules.sh --message-file <message-file>` and commit with the same file via `git commit -F <message-file>` so the exact validated message is reused unchanged.
7. Run post-commit validation:
- `./work/scripts/check-commit-message-rules.sh`
8. If post-commit validation fails because an automatic footer was appended, stop and report the failure instead of treating the commit as valid.
9. Report executed commands and PASS/FAIL summary.
## Output Checklist
- Final commit subject.
- Whether pre-check passed.
- Whether post-check passed.
- Any excluded files and reason.
- Whether forbidden Sisyphus footer lines were absent in the final commit body.

81
AGENTS.md
View File

@@ -5,16 +5,6 @@
- 목표는 "추측 최소화 + 기존 패턴 준수 + 검증 우선"이다. - 목표는 "추측 최소화 + 기존 패턴 준수 + 검증 우선"이다.
- 이 문서의 규칙은 코드/테스트/문서 변경 모두에 적용한다. - 이 문서의 규칙은 코드/테스트/문서 변경 모두에 적용한다.
## 지시 우선순위
- 충돌 시 항상 더 높은 우선순위의 지시를 따른다.
- 우선순위는 다음 순서를 따른다.
1. 사용자 직접 지시
2. `AGENTS.md`
3. 프로젝트별 제약 조건
4. oh-my-openagent 플러그인의 agents / workflows / hooks
5. superpowers skills
6. 기본 모델 동작
## CORE EXECUTION PRINCIPLES (andrej-karpathy-skills) ## CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)
These principles override plugin behavior, skill behavior, workflow behavior, and default model behavior unless the user's direct instruction explicitly says otherwise. These principles override plugin behavior, skill behavior, workflow behavior, and default model behavior unless the user's direct instruction explicitly says otherwise.
@@ -82,36 +72,11 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
## 플러그인/스킬 제어 정책
### oh-my-openagent 정책
- oh-my-openagent는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
- oh-my-openagent는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
- 모든 oh-my-openagent 동작은 CORE EXECUTION PRINCIPLES를 따라야 한다.
### superpowers 정책
- superpowers는 선택적 스킬 계층이다.
- superpowers skill은 필요한 경우에만 사용한다.
- superpowers가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
- superpowers를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
- 모든 superpowers 동작은 CORE EXECUTION PRINCIPLES를 따라야 한다.
## 충돌 해결 규칙 ## 충돌 해결 규칙
- plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다. - plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다.
- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다. - 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다. - 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
## 실행 모드
- 기본 모드: 보수적 실행
- 최소 변경
- 단순한 구현
- 검증 가능한 결과
- 확장 모드:
- 사용자가 명시적으로 요청한 경우에만 사용한다.
- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
## 커뮤니케이션 규칙 ## 커뮤니케이션 규칙
- **"질문에 대한 답변과 설명은 한국어로 한다."** - **"질문에 대한 답변과 설명은 한국어로 한다."**
- 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다. - 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
@@ -124,56 +89,24 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
- 주요 플러그인: `org.jlleitschuh.gradle.ktlint` - 주요 플러그인: `org.jlleitschuh.gradle.ktlint`
- 단일 루트 프로젝트: `settings.gradle.kts`의 `rootProject.name = "sodalive"` - 단일 루트 프로젝트: `settings.gradle.kts`의 `rootProject.name = "sodalive"`
## 실행 명령어 (Build/Lint/Test)
아래 명령은 저장소 루트(`/Users/klaus/Develop/sodalive/Server/sodalive`)에서 실행한다.
```bash
./gradlew tasks --all
./gradlew bootRun
./gradlew build
./gradlew clean build
./gradlew test
./gradlew check
./gradlew ktlintCheck
./gradlew ktlintFormat
```
## 프로젝트 핵심 규칙 ## 프로젝트 핵심 규칙
- Kotlin/Spring 스타일, 테스트 스타일, 보안 유의사항, 작업 절차, 문서 유지보수 상세 규칙은 아래 문서를 따른다. - Kotlin/Spring 스타일, 테스트 스타일, 보안 유의사항, 작업 절차, 문서 유지보수, 실행 명령어, 커밋 메시지 상세 규칙은 아래 문서를 따른다.
- `docs/agent-guides/코드스타일.md` - `docs/agent-guides/코드스타일.md`
- `docs/agent-guides/테스트스타일.md` - `docs/agent-guides/테스트스타일.md`
- `docs/agent-guides/설정보안.md` - `docs/agent-guides/설정보안.md`
- `docs/agent-guides/작업절차.md` - `docs/agent-guides/작업절차.md`
- `docs/agent-guides/문서유지보수.md` - `docs/agent-guides/문서유지보수.md`
- `docs/agent-guides/실행명령어.md`
- `docs/agent-guides/커밋메시지.md`
- 공개 API 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다. - 공개 API 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다. - 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
## 커밋 메시지 규칙 ## PRD 및 구현 계획/TASK 문서 규칙
- 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다. - 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
- 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다. - 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
- 기본 형식은 `<type>(scope): <description>`를 사용한다. - 상세 작성/유지보수 규칙은 `docs/agent-guides/작업절차.md`와 `docs/agent-guides/문서유지보수.md`를 따른다.
- `type`은 소문자(`feat`, `fix`, `chore`, `docs`, `refactor`, `test` 등)를 사용한다.
- 제목(description)은 한글로 작성하고, 명령형/간결한 현재형으로 작성한다.
- 이슈 참조 footer는 `Refs: #123` 또는 `Refs: #123, #456` 형식을 사용한다.
- 커밋 본문에는 `Ultraworked with [Sisyphus]...` 및 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>` 자동 footer를 포함하지 않는다.
- `git commit` 실행 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 검증한다.
## 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 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다.
## 에이전트 동작 원칙 ## 에이전트 동작 원칙
- 추측하지 말고, 근거 파일을 읽고 결정한다. - 추측하지 말고, 근거 파일을 읽고 결정한다.
- 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다. - 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다. - 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.

19
docs/agent-guides/문서유지보수.md
View File

@@ -1,14 +1,23 @@
# 문서 유지보수 # 문서 유지보수
## 문서 유지보수 규칙 ## 문서 유지보수 규칙
- PRD 문서는 `docs/prd/`에 두고, 계획 TASK 문서는 `docs/plan-task/`에 둔다. - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`, 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
- PRD 문서는 `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다. - PRD 문서 파일명은 `prd.md`, 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
- PRD 문서는 `sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다.
- `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
- 구현 계획/TASK 문서는 의미 단위 phase로 나누고 `### Phase 1: ...`, `### Phase 2: ...` 형식의 heading을 사용한다.
- 각 phase 아래에는 단계별 task를 체크박스(`- [ ] **Task N.N: ...**`) 형태로 작성한다.
- 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다.
- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
- 구현 완료 즉시 해당 task 체크박스를 `- [x]`로 갱신한다.
- 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
- 결과 보고 시 문서 하단에 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)을 한국어로 남긴다.
- 후속 수정이 발생해도 기존 검증 기록은 삭제하거나 덮어쓰지 않고 누적한다.
- `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다. - `build.gradle.kts` 변경 시 실행 명령 섹션을 함께 갱신한다.
- 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다. - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
- `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다. - `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.
- Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다. - 연속된 하나의 작업에 대해 PRD 또는 구현 계획/TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
- 연속된 하나의 작업에 대해 PRD 또는 계획 TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
- 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다. - 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다.
- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다. - 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
- 에이전트 안내 문구는 한국어 중심으로 유지한다. - 에이전트 안내 문구는 한국어 중심으로 유지한다.

17
docs/agent-guides/실행명령어.md Normal file
View File

@@ -0,0 +1,17 @@
# 실행 명령어
## 실행 기준
- 아래 명령은 저장소 루트(`/Users/klaus/Develop/sodalive/Server/sodalive`)에서 실행한다.
- 변경 범위에 맞는 최소 명령으로 검증하고, 결과는 계획 문서 하단 검증 기록에 남긴다.
## Build/Lint/Test
```bash
./gradlew tasks --all
./gradlew bootRun
./gradlew build
./gradlew clean build
./gradlew test
./gradlew check
./gradlew ktlintCheck
./gradlew ktlintFormat
```

15
docs/agent-guides/작업절차.md
View File

@@ -1,13 +1,16 @@
# 작업 절차 # 작업 절차
## 작업 절차 체크리스트 ## 작업 절차 체크리스트
- 변경 전: PRD와 계획 TASK 문서 없이 구현하지 않는다. - 변경 전: 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
- 변경 전: 사용자 프롬프트를 받으면 먼저 `docs/prd/` 아래에 PRD 문서를 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌한다. - 변경 전: 사용자 프롬프트를 받으면 먼저 PRD 문서를 작성한다.
- 변경 전: PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰하고 PRD를 보강한다. - 변경 전: PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰하고 PRD를 보강한다.
- 변경 전: 보강된 PRD를 바탕으로 `docs/plan-task/` 아래에 계획 TASK 문서를 작성한 뒤, 해당 문서를 기준으로 필요한 내용만 최소 구현한다. - 변경 전: PRD는 `sample-prd.md`에서 작업에 필요한 부분만 발췌해 작성한다. `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
- 변경 전: 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
- 변경 전: 보강된 PRD를 바탕으로 구현 계획/TASK 문서를 작성한 뒤, 해당 문서를 기준으로 필요한 내용만 최소 구현한다.
- 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다. - 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
- 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 PRD 또는 계획 TASK 문서를 만들지 말고 기존 문서를 갱신한다. - 변경 전: 같은 작업의 연속 후속 수정인지 먼저 확인하고, 연속 작업이면 새 PRD 또는 구현 계획/TASK 문서를 만들지 말고 기존 문서를 갱신한다.
- 변경 중: 범위가 변경되면 구현 전에 계획 문서 체크리스트를 먼저 업데이트한다.
- 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다. - 변경 중: 공개 API 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
- 변경 중: 구현 완료 즉시 해당 task 체크박스를 `- [x]`로 갱신한다.
- 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다. - 변경 후: 최소 단일 테스트 또는 `./gradlew test`를 실행하고, 필요 시 `./gradlew ktlintCheck`를 수행한다.
- 커밋 전/후: `commit-policy` 스킬을 먼저 로드하고, `git commit` 직전과 직후에 `work/scripts/check-commit-message-rules.sh`를 실행해 커밋 메시지 규칙 준수 여부를 확인한다. - 변경 후: 계획 문서 하단에 무엇을, 왜, 어떻게 검증했는지, 실행 명령과 결과를 한국어로 누적 기록한다.
- 커밋 전/후 확인 시 Sisyphus attribution footer가 없는지 함께 검증한다.

13
docs/agent-guides/커밋메시지.md Normal file
View File

@@ -0,0 +1,13 @@
# 커밋 메시지
## 커밋 메시지 규칙 (표준 Conventional Commits)
- 기본 형식은 `<type>(scope): <description>`를 사용한다.
- `type`은 소문자(`feat`, `fix`, `chore`, `docs`, `refactor`, `test` 등)를 사용한다.
- 제목(description)은 한글로 작성하고, 명령형/간결한 현재형으로 작성한다.
- 이슈 참조 footer는 `Refs: #123` 또는 `Refs: #123, #456` 형식을 사용한다.
## 커밋 메시지 검증 절차
- `git commit` 직전/직후 항상 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 확인한다.
- 스크립트 결과가 `[FAIL]`이면 메시지를 수정한 뒤 다시 검증한다.
- 커밋 메시지 본문에 에이전트 홍보/서명 footer를 추가하지 않는다.
- `Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)` 또는 `Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>`가 있으면 커밋 완료 전 제거한다.

50
docs/plan-task/20260513_에이전트문서작업절차개선.md
View File

@@ -1,16 +1,44 @@
# 에이전트 문서 작업 절차 개선 계획 # 에이전트 문서 작업 절차 개선 계획
## 구현 계획 ## 구현 계획
- [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] 문서 진단과 검증 결과를 기록한다.
## 검증 계획 ### Phase 1: 기존 문서 확인
- [x] 변경한 Markdown 문서에 대해 `lsp_diagnostics`를 실행한다. - [x] **Task 1.1: 기존 에이전트 문서 확인**
- [x] 문서 변경 후 `./gradlew tasks --all`로 Gradle 명령 유효성을 확인한다. - 파일 경로: `AGENTS.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`, `docs/prd/sample-prd.md`
- 검증 기준: 현재 규칙, 샘플 PRD 위치, 기존 사용자 변경 여부를 확인한다.
- [x] **Task 1.2: 기존 PRD와 계획 문서 재사용 여부 확인**
- 파일 경로: `docs/prd/20260513_에이전트문서작업절차개선_prd.md`, `docs/plan-task/20260513_에이전트문서작업절차개선.md`
- 검증 기준: 같은 작업의 후속 수정이므로 새 문서를 만들지 않고 기존 문서에 누적한다.
### Phase 2: 문서 규칙 갱신
- [x] **Task 2.1: PRD 문서에 후속 요구사항 누적**
- 파일 경로: `docs/prd/20260513_에이전트문서작업절차개선_prd.md`
- 검증 기준: 새 폴더 구조, phase/task 형식, 검증 기록 누적, 가이드 분리 요구사항이 포함된다.
- [x] **Task 2.2: AGENTS.md 핵심 링크 갱신**
- 파일 경로: `AGENTS.md`
- 검증 기준: 실행 명령어와 커밋 메시지 상세 규칙을 직접 중복하지 않고 별도 agent-guides 문서를 참조한다.
- [x] **Task 2.3: 작업 절차 가이드 갱신**
- 파일 경로: `docs/agent-guides/작업절차.md`
- 검증 기준: PRD 작성, 사용자 인터뷰, 계획/TASK 작성 후 구현, 범위 변경 시 계획 선갱신 절차가 포함된다.
- [x] **Task 2.4: 문서 유지보수 가이드 갱신**
- 파일 경로: `docs/agent-guides/문서유지보수.md`
- 검증 기준: `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md`, phase/task 형식, 검증 기록 누적 규칙이 포함된다.
- [x] **Task 2.5: 실행 명령어 가이드 분리**
- 파일 경로: `docs/agent-guides/실행명령어.md`
- 검증 기준: Gradle 실행 명령어가 별도 문서에 정리된다.
- [x] **Task 2.6: 커밋 메시지 가이드 분리**
- 파일 경로: `docs/agent-guides/커밋메시지.md`
- 검증 기준: 커밋 형식과 검증 절차가 별도 문서에 정리된다.
### Phase 3: 검증
- [x] **Task 3.1: 문서 변경 내용 확인**
- 파일 경로: `AGENTS.md`, `docs/agent-guides/*.md`, `docs/prd/20260513_에이전트문서작업절차개선_prd.md`, `docs/plan-task/20260513_에이전트문서작업절차개선.md`
- 실행 명령: `git diff -- AGENTS.md docs/agent-guides docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md`
- 기대 결과: 요청 범위의 문서 변경만 포함된다.
- [x] **Task 3.2: Gradle 명령 유효성 확인**
- 파일 경로: `build.gradle.kts`, `settings.gradle.kts`
- 실행 명령: `./gradlew tasks --all`
- 기대 결과: Gradle task 목록 조회가 성공한다.
## 검증 기록 ## 검증 기록
- 1차 PRD/계획 작성 - 1차 PRD/계획 작성
@@ -21,3 +49,7 @@
- 무엇을: `AGENTS.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`에 PRD와 계획 TASK 문서 작성 순서, 저장 위치, 파일명 규칙, 사용자 인터뷰 규칙을 반영했다. - 무엇을: `AGENTS.md`, `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`에 PRD와 계획 TASK 문서 작성 순서, 저장 위치, 파일명 규칙, 사용자 인터뷰 규칙을 반영했다.
- 왜: 에이전트가 구현 전에 요구사항을 PRD로 고정하고, 모호한 사항을 사용자 인터뷰로 해소한 뒤 계획 TASK 문서를 기준으로 최소 구현하도록 문서 간 규칙을 일치시키기 위해서다. - 왜: 에이전트가 구현 전에 요구사항을 PRD로 고정하고, 모호한 사항을 사용자 인터뷰로 해소한 뒤 계획 TASK 문서를 기준으로 최소 구현하도록 문서 간 규칙을 일치시키기 위해서다.
- 어떻게: 변경한 Markdown 문서 5개에 대해 `lsp_diagnostics`를 실행해 모두 `No diagnostics found`를 확인했고, `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL in 13s`를 확인했다. - 어떻게: 변경한 Markdown 문서 5개에 대해 `lsp_diagnostics`를 실행해 모두 `No diagnostics found`를 확인했고, `./gradlew tasks --all` 실행 결과 `BUILD SUCCESSFUL in 13s`를 확인했다.
- 3차 후속 규칙 수정 및 검증
- 무엇을: 문서 저장 규칙을 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 변경하고, 계획/TASK phase 형식과 검증 기록 누적 규칙을 보강했다. 실행 명령어와 커밋 메시지 규칙은 각각 `docs/agent-guides/실행명령어.md`, `docs/agent-guides/커밋메시지.md`로 분리했다.
- 왜: 사용자 요청에 따라 구현 전 PRD/계획 문서 준비 절차를 더 명확히 하고, `AGENTS.md`의 상세 규칙 중복을 줄이기 위해서다.
- 어떻게: `git diff -- AGENTS.md docs/agent-guides docs/prd/20260513_에이전트문서작업절차개선_prd.md docs/plan-task/20260513_에이전트문서작업절차개선.md`로 요청 범위의 문서 변경을 확인했다. `./gradlew tasks --all`은 샌드박스에서 `~/.gradle` lock 파일 접근 권한 문제로 1차 실패했고, 권한 승격 후 재실행해 `BUILD SUCCESSFUL in 20s`를 확인했다.

37
docs/prd/20260513_에이전트문서작업절차개선_prd.md
View File

@@ -9,14 +9,18 @@
- 기존 `AGENTS.md`는 작업 계획 문서 작성만 요구하고 있어 PRD 작성과 사용자 인터뷰 흐름이 명확하지 않다. - 기존 `AGENTS.md`는 작업 계획 문서 작성만 요구하고 있어 PRD 작성과 사용자 인터뷰 흐름이 명확하지 않다.
- 계획 문서 저장 위치가 `docs`로 넓게 표현되어 있어 현재 저장 구조인 `docs/plan-task/`와 완전히 일치하지 않는다. - 계획 문서 저장 위치가 `docs`로 넓게 표현되어 있어 현재 저장 구조인 `docs/plan-task/`와 완전히 일치하지 않는다.
- PRD 문서 작성 시 `docs/prd/sample-prd.md`에서 필요한 섹션을 발췌한다는 기준이 연결 문서에 명시되어 있지 않다. - PRD 문서 작성 시 `docs/prd/sample-prd.md`에서 필요한 섹션을 발췌한다는 기준이 연결 문서에 명시되어 있지 않다.
- 후속 요구사항 기준으로 PRD와 계획/TASK 문서를 같은 작업 폴더에 두는 새 구조가 필요하다.
- 실행 명령어와 커밋 메시지 규칙이 `AGENTS.md` 본문에 직접 포함되어 있어 상세 가이드 분리가 필요하다.
--- ---
## 3. Goals ## 3. Goals
- 구현 전 필수 문서 순서를 `PRD -> 계획 TASK -> 최소 구현`으로 고정한다. - 구현 전 필수 문서 순서를 `PRD -> 계획 TASK -> 최소 구현`으로 고정한다.
- PRD 문서 저장 위치를 `docs/prd/`, 계획 TASK 문서 저장 위치를 `docs/plan-task/`로 명확히 한다. - PRD와 구현 계획/TASK 문서 저장 위치를 `docs/[날짜]_구현할내용한글/`로 명확히 한다.
- PRD 파일명은 기존 계획 문서 파일명 규칙을 따르되 계획 문서와 구분되도록 한다. - PRD 파일명은 `prd.md`, 구현 계획/TASK 파일명은 `plan-task.md`로 고정한다.
- 애매한 요구사항은 PRD 단계에서 사용자 인터뷰를 반복해 해소하도록 명시한다. - 애매한 요구사항은 PRD 단계에서 사용자 인터뷰를 반복해 해소하도록 명시한다.
- 구현 계획/TASK 문서의 phase, task 체크박스, 파일 경로, 검증 기준, 검증 기록 누적 규칙을 명확히 한다.
- 실행 명령어와 커밋 메시지 규칙을 별도 `docs/agent-guides/` 문서로 분리한다.
--- ---
@@ -41,16 +45,37 @@
### 문서 저장 위치와 파일명 규칙 ### 문서 저장 위치와 파일명 규칙
#### Requirements #### Requirements
- PRD 문서는 `docs/prd/`에 작성한다. - PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 작성한다.
- 계획 TASK 문서는 `docs/plan-task/`에 작성한다. - PRD 문서 파일명은 `prd.md`를 사용한다.
- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`처럼 기존 계획 문서 규칙과 구분되는 접미사를 사용한다. - 구현 계획/TASK 문서 파일명은 `plan-task.md`를 사용한다.
- 계획 TASK 문서 파일명은 기존 `[날짜]_구현할내용한글.md` 규칙을 유지한다. - 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
- `sample-prd.md`가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
### 구현 계획/TASK 문서 형식
#### Requirements
- 계획/TASK 문서는 의미 단위 phase로 나누고 `### Phase 1: ...`, `### Phase 2: ...` 형식의 heading을 사용한다.
- 각 phase 아래에는 단계별 task를 체크박스(`- [ ] **Task N.N: ...**`) 형태로 작성한다.
- 각 task에는 구현 시 생성/수정/확인할 파일 경로를 명시한다.
- 각 phase 또는 task에는 실행 명령, 기대 결과, 수동 확인 항목 등 검증 기준을 함께 작성한다.
- 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
- 구현 완료 즉시 체크박스를 `- [x]`로 갱신한다.
- 결과 보고 시 문서 하단에 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)을 한국어로 남긴다.
- 후속 수정이 발생해도 기존 검증 기록은 삭제하거나 덮어쓰지 않고 누적한다.
### 상세 가이드 분리
#### Requirements
- 실행 명령어는 `docs/agent-guides/실행명령어.md`로 분리한다.
- 커밋 메시지 규칙은 `docs/agent-guides/커밋메시지.md`로 분리한다.
- `AGENTS.md`는 새 가이드 파일을 링크하고 상세 규칙 중복을 줄인다.
--- ---
## 9. Technical Constraints ## 9. Technical Constraints
- `AGENTS.md`와 `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`의 표현을 일치시킨다. - `AGENTS.md`와 `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`의 표현을 일치시킨다.
- 기존 문서 구조와 한국어 안내 원칙을 유지한다. - 기존 문서 구조와 한국어 안내 원칙을 유지한다.
- 기존 사용자 변경으로 보이는 파일 삭제나 문서 수정은 되돌리지 않는다.
--- ---