113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
# AGENTS.md
|
|
|
|
## 문서 목적
|
|
- 이 문서는 `/Users/klaus/Develop/sodalive/Server/sodalive` 저장소에서 작업하는 에이전트용 실행 가이드다.
|
|
- 목표는 "추측 최소화 + 기존 패턴 준수 + 검증 우선"이다.
|
|
- 이 문서의 규칙은 코드/테스트/문서 변경 모두에 적용한다.
|
|
|
|
## 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.
|
|
|
|
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
|
|
|
|
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
|
|
|
## 1. Think Before Coding
|
|
|
|
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
|
|
|
Before implementing:
|
|
- State your assumptions explicitly. If uncertain, ask.
|
|
- If multiple interpretations exist, present them - don't pick silently.
|
|
- If a simpler approach exists, say so. Push back when warranted.
|
|
- If something is unclear, stop. Name what's confusing. Ask.
|
|
|
|
## 2. Simplicity First
|
|
|
|
**Minimum code that solves the problem. Nothing speculative.**
|
|
|
|
- No features beyond what was asked.
|
|
- No abstractions for single-use code.
|
|
- No "flexibility" or "configurability" that wasn't requested.
|
|
- No error handling for impossible scenarios.
|
|
- If you write 200 lines and it could be 50, rewrite it.
|
|
|
|
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
|
|
|
## 3. Surgical Changes
|
|
|
|
**Touch only what you must. Clean up only your own mess.**
|
|
|
|
When editing existing code:
|
|
- Don't "improve" adjacent code, comments, or formatting.
|
|
- Don't refactor things that aren't broken.
|
|
- Match existing style, even if you'd do it differently.
|
|
- If you notice unrelated dead code, mention it - don't delete it.
|
|
|
|
When your changes create orphans:
|
|
- Remove imports/variables/functions that YOUR changes made unused.
|
|
- Don't remove pre-existing dead code unless asked.
|
|
|
|
The test: Every changed line should trace directly to the user's request.
|
|
|
|
## 4. Goal-Driven Execution
|
|
|
|
**Define success criteria. Loop until verified.**
|
|
|
|
Transform tasks into verifiable goals:
|
|
- "Add validation" → "Write tests for invalid inputs, then make them pass"
|
|
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
|
- "Refactor X" → "Ensure tests pass before and after"
|
|
|
|
For multi-step tasks, state a brief plan:
|
|
```
|
|
1. [Step] → verify: [check]
|
|
2. [Step] → verify: [check]
|
|
3. [Step] → verify: [check]
|
|
```
|
|
|
|
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
|
|
|
---
|
|
|
|
**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.
|
|
|
|
## 충돌 해결 규칙
|
|
- plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다.
|
|
- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
|
|
- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
|
|
|
|
## 커뮤니케이션 규칙
|
|
- **"질문에 대한 답변과 설명은 한국어로 한다."**
|
|
- 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
|
|
- 코드 식별자, 경로, 명령어는 원문(영문) 그대로 유지한다.
|
|
|
|
## 프로젝트 개요
|
|
- 빌드 도구: Gradle Wrapper (`./gradlew`)
|
|
- 언어/런타임: Kotlin + Java 17
|
|
- 프레임워크: Spring Boot 2.7.14
|
|
- 주요 플러그인: `org.jlleitschuh.gradle.ktlint`
|
|
- 단일 루트 프로젝트: `settings.gradle.kts`의 `rootProject.name = "sodalive"`
|
|
|
|
## 프로젝트 핵심 규칙
|
|
- 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 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
|
|
- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
|
|
|
|
## PRD 및 구현 계획/TASK 문서 규칙
|
|
- 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
|
|
- 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
|
|
- 상세 작성/유지보수 규칙은 `docs/agent-guides/작업절차.md`와 `docs/agent-guides/문서유지보수.md`를 따른다.
|
|
|
|
## 에이전트 동작 원칙
|
|
- 추측하지 말고, 근거 파일을 읽고 결정한다.
|
|
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
|
|
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
|