docs(agent): 에이전트 문서 규칙을 정리한다
This commit is contained in:
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`를 따른다.
|
||||
|
||||
## 에이전트 동작 원칙
|
||||
- 추측하지 말고, 근거 파일을 읽고 결정한다.
|
||||
- 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
|
||||
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
|
||||
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
|
||||
|
||||
Reference in New Issue
Block a user