docs(agent): 에이전트 문서 규칙을 정리한다
This commit is contained in:
@@ -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
|
||||
@@ -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
81
AGENTS.md
@@ -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)
|
||||
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.
|
||||
|
||||
## 플러그인/스킬 제어 정책
|
||||
|
||||
### 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를 따른다.
|
||||
- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
|
||||
- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
|
||||
|
||||
## 실행 모드
|
||||
- 기본 모드: 보수적 실행
|
||||
- 최소 변경
|
||||
- 단순한 구현
|
||||
- 검증 가능한 결과
|
||||
- 확장 모드:
|
||||
- 사용자가 명시적으로 요청한 경우에만 사용한다.
|
||||
- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
|
||||
|
||||
## 커뮤니케이션 규칙
|
||||
- **"질문에 대한 답변과 설명은 한국어로 한다."**
|
||||
- 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
|
||||
@@ -124,56 +89,24 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
|
||||
- 주요 플러그인: `org.jlleitschuh.gradle.ktlint`
|
||||
- 단일 루트 프로젝트: `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`
|
||||
- 공개 API 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
|
||||
- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
|
||||
|
||||
## 커밋 메시지 규칙
|
||||
- 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다.
|
||||
- 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다.
|
||||
- 기본 형식은 `<type>(scope): <description>`를 사용한다.
|
||||
- `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 문서 맨 아래에 무엇을, 왜, 어떻게 검증했는지 한국어로 누적 기록한다.
|
||||
## PRD 및 구현 계획/TASK 문서 규칙
|
||||
- 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
|
||||
- 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
|
||||
- 상세 작성/유지보수 규칙은 `docs/agent-guides/작업절차.md`와 `docs/agent-guides/문서유지보수.md`를 따른다.
|
||||
|
||||
## 에이전트 동작 원칙
|
||||
- 추측하지 말고, 근거 파일을 읽고 결정한다.
|
||||
- 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
|
||||
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
|
||||
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
|
||||
|
||||
@@ -1,14 +1,23 @@
|
||||
# 문서 유지보수
|
||||
|
||||
## 문서 유지보수 규칙
|
||||
- PRD 문서는 `docs/prd/`에 두고, 계획 TASK 문서는 `docs/plan-task/`에 둔다.
|
||||
- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`, 계획 TASK 문서 파일명은 `[날짜]_구현할내용한글.md` 형식을 사용한다.
|
||||
- PRD 문서는 `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌해 작성하고, 불필요한 빈 섹션을 기계적으로 복사하지 않는다.
|
||||
- PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 둔다.
|
||||
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
|
||||
- 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` 변경 시 실행 명령 섹션을 함께 갱신한다.
|
||||
- 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
|
||||
- `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다.
|
||||
- Cursor/Copilot 규칙 파일이 생기면 해당 내용을 이 문서에 반영한다.
|
||||
- 연속된 하나의 작업에 대해 PRD 또는 계획 TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
|
||||
- 연속된 하나의 작업에 대해 PRD 또는 구현 계획/TASK 문서가 여러 개 생기지 않도록 기존 문서 재사용 여부를 먼저 확인한다.
|
||||
- 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다.
|
||||
- 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
|
||||
- 에이전트 안내 문구는 한국어 중심으로 유지한다.
|
||||
|
||||
17
docs/agent-guides/실행명령어.md
Normal file
17
docs/agent-guides/실행명령어.md
Normal 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
|
||||
```
|
||||
@@ -1,13 +1,16 @@
|
||||
# 작업 절차
|
||||
|
||||
## 작업 절차 체크리스트
|
||||
- 변경 전: PRD와 계획 TASK 문서 없이 구현하지 않는다.
|
||||
- 변경 전: 사용자 프롬프트를 받으면 먼저 `docs/prd/` 아래에 PRD 문서를 작성하고, `docs/prd/sample-prd.md`에서 필요한 섹션만 발췌한다.
|
||||
- 변경 전: 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
|
||||
- 변경 전: 사용자 프롬프트를 받으면 먼저 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 스키마를 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
|
||||
- 변경 중: 구현 완료 즉시 해당 task 체크박스를 `- [x]`로 갱신한다.
|
||||
- 변경 후: 최소 단일 테스트 또는 `./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
13
docs/agent-guides/커밋메시지.md
Normal 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>`가 있으면 커밋 완료 전 제거한다.
|
||||
@@ -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] 문서 진단과 검증 결과를 기록한다.
|
||||
|
||||
## 검증 계획
|
||||
- [x] 변경한 Markdown 문서에 대해 `lsp_diagnostics`를 실행한다.
|
||||
- [x] 문서 변경 후 `./gradlew tasks --all`로 Gradle 명령 유효성을 확인한다.
|
||||
### Phase 1: 기존 문서 확인
|
||||
- [x] **Task 1.1: 기존 에이전트 문서 확인**
|
||||
- 파일 경로: `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/계획 작성
|
||||
@@ -21,3 +49,7 @@
|
||||
- 무엇을: `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`를 확인했다.
|
||||
- 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`를 확인했다.
|
||||
|
||||
@@ -9,14 +9,18 @@
|
||||
- 기존 `AGENTS.md`는 작업 계획 문서 작성만 요구하고 있어 PRD 작성과 사용자 인터뷰 흐름이 명확하지 않다.
|
||||
- 계획 문서 저장 위치가 `docs`로 넓게 표현되어 있어 현재 저장 구조인 `docs/plan-task/`와 완전히 일치하지 않는다.
|
||||
- PRD 문서 작성 시 `docs/prd/sample-prd.md`에서 필요한 섹션을 발췌한다는 기준이 연결 문서에 명시되어 있지 않다.
|
||||
- 후속 요구사항 기준으로 PRD와 계획/TASK 문서를 같은 작업 폴더에 두는 새 구조가 필요하다.
|
||||
- 실행 명령어와 커밋 메시지 규칙이 `AGENTS.md` 본문에 직접 포함되어 있어 상세 가이드 분리가 필요하다.
|
||||
|
||||
---
|
||||
|
||||
## 3. Goals
|
||||
- 구현 전 필수 문서 순서를 `PRD -> 계획 TASK -> 최소 구현`으로 고정한다.
|
||||
- PRD 문서 저장 위치를 `docs/prd/`, 계획 TASK 문서 저장 위치를 `docs/plan-task/`로 명확히 한다.
|
||||
- PRD 파일명은 기존 계획 문서 파일명 규칙을 따르되 계획 문서와 구분되도록 한다.
|
||||
- PRD와 구현 계획/TASK 문서 저장 위치를 `docs/[날짜]_구현할내용한글/`로 명확히 한다.
|
||||
- PRD 파일명은 `prd.md`, 구현 계획/TASK 파일명은 `plan-task.md`로 고정한다.
|
||||
- 애매한 요구사항은 PRD 단계에서 사용자 인터뷰를 반복해 해소하도록 명시한다.
|
||||
- 구현 계획/TASK 문서의 phase, task 체크박스, 파일 경로, 검증 기준, 검증 기록 누적 규칙을 명확히 한다.
|
||||
- 실행 명령어와 커밋 메시지 규칙을 별도 `docs/agent-guides/` 문서로 분리한다.
|
||||
|
||||
---
|
||||
|
||||
@@ -41,16 +45,37 @@
|
||||
### 문서 저장 위치와 파일명 규칙
|
||||
|
||||
#### Requirements
|
||||
- PRD 문서는 `docs/prd/`에 작성한다.
|
||||
- 계획 TASK 문서는 `docs/plan-task/`에 작성한다.
|
||||
- PRD 문서 파일명은 `[날짜]_구현할내용한글_prd.md`처럼 기존 계획 문서 규칙과 구분되는 접미사를 사용한다.
|
||||
- 계획 TASK 문서 파일명은 기존 `[날짜]_구현할내용한글.md` 규칙을 유지한다.
|
||||
- PRD 문서와 구현 계획/TASK 문서는 `docs/[날짜]_구현할내용한글/` 아래에 함께 작성한다.
|
||||
- PRD 문서 파일명은 `prd.md`를 사용한다.
|
||||
- 구현 계획/TASK 문서 파일명은 `plan-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
|
||||
- `AGENTS.md`와 `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`의 표현을 일치시킨다.
|
||||
- 기존 문서 구조와 한국어 안내 원칙을 유지한다.
|
||||
- 기존 사용자 변경으로 보이는 파일 삭제나 문서 수정은 되돌리지 않는다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user