sodalive-backend-spring-boot/AGENTS.md

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를 따른다.

에이전트 동작 원칙

• 추측하지 말고, 근거 파일을 읽고 결정한다.
• 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
• 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.