# 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 스키마는 임의 변경하지 말고, 작은 단위로 안전하게 수정한다.
- 기존 코드베이스 관례를 우선하며, 불확실한 규칙은 추측하지 말고 근거 파일을 먼저 확인한다.
- DB에 저장하고 응답으로 돌려주는 시각은 DDL의 소수초 정밀도를 먼저 확인하고 한 번 정규화한 같은 값을 사용한다.
  날짜/시간 작업 전 [코드 스타일의 시각 정밀도 규칙](docs/agent-guides/코드스타일.md)과
  [테스트 스타일의 시각 왕복 검증 규칙](docs/agent-guides/테스트스타일.md)을 읽는다. 테스트 비교를 완화해 차이를 숨기지 않는다.

## PRD 및 구현 계획/TASK 문서 규칙
- 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
- 문서는 `docs/[날짜]_구현할내용한글/prd.md`, `docs/[날짜]_구현할내용한글/plan-task.md` 형식으로 작성한다.
- 상세 작성/유지보수 규칙은 `docs/agent-guides/작업절차.md`와 `docs/agent-guides/문서유지보수.md`를 따른다.

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

## Agent skills

### Issue tracker
이슈는 `.scratch/<feature-slug>/issues/`의 로컬 Markdown 파일로 관리한다.
상세 규칙은 `docs/agents/issue-tracker.md`를 따른다.

### Domain docs
single-context 구성으로 루트 `GLOSSARY.md`와 `docs/adr/`를 사용한다.
읽기 규칙은 `docs/agents/domain.md`를 따른다.

## Skill Orchestration

- Superpowers는 개발 작업의 주 흐름이다. specialist skill은 실제 해당 단계의 요구를 보완하며, 작업마다 모든 겹치는 skill을 일괄 실행하거나 새 결정론적 scheduler를 만들지 않는다.
- 먼저 요청 유형과 산출물을 분류하고, 그 단계의 주 skill 하나를 정한 뒤 필요한 보조 skill만 선택한다. 각 단계의 책임자는 하나로 유지한다.
- `using-superpowers` 절차가 이미 주입됐다면 다시 전체 controller를 시작하지 않는다. child session에서 처음부터 orchestration을 반복하지 않는다.
- 조사 문서 [`docs/20261019_스킬오케스트레이션/audit.md`](docs/20261019_스킬오케스트레이션/audit.md)는 조사 시점의 설치/설정 증거다. 모든 항목이 현재 host에서 등록·발견·활성화됐다는 보장은 아니다.
- 아래 라우팅은 작업을 돕는 지침이지 자동 invocation 보장이 아니다. 구체적인 예시는 [`docs/20261019_스킬오케스트레이션/routing-scenarios.md`](docs/20261019_스킬오케스트레이션/routing-scenarios.md)를 참고한다.

## Skill Priority and Selection

- 모든 현재 요청을 질문/설명, 조사, 신규 기능, 요구사항 정리, 버그 수정, 아키텍처 평가, API 설계, 보안 작업, 리뷰, 테스트/검증, 기존 작업 이어하기 중 해당 유형으로 분류한다. 혼합 작업은 산출물 단계별로 나눈다.
- 일반 질문이나 read-only review를 코드 변경으로 바꾸지 않는다. specialist는 그 skill 고유 책임이 실제 범위에 있을 때만 추가한다.
- 신규 기능 구현은 `brainstorming` → `writing-plans` → `executing-plans` 또는 `subagent-driven-development` 중 정확히 하나 → 구현 중 TDD → 변경 review → 완료 직전 fresh verification 순서를 따른다.
- 이미 승인된 설계/plan의 연속 작업은 기존 미완료 Task부터 재개한다. known decisions, open questions, acceptance criteria를 다시 묻거나 interview/planning을 반복하지 않는다. 새 critical gap이 있을 때만 요구/계획을 다시 연다.
- 독립적이고 공유 상태가 없는 작업의 병렬 조율에는 `dispatching-parallel-agents`를 사용한다. 같은 파일을 수정하거나 선행 결과가 필요한 구현 작업은 동시에 보내지 않는다.
- 실행 방식 선택, `using-git-worktrees`를 통한 필요 시 격리 확인, `finishing-a-development-branch`의 통합 판단은 별개다. 확인만으로 worktree를 자동 생성하지 않으며 commit/push/merge/delete는 명시적 승인 없이 하지 않는다.

## Requirements Discovery

- 신규 동작의 사용자 의도와 선택 정리는 `brainstorming`이 주 책임이다. 계획만 필요한 경우 `writing-plans`를 사용하고, 이미 확정된 기존 계획을 중복 생성하지 않는다.
- 요구사항이 중요하게 모호할 때만 `deep-interview`를 조건부로 사용한다. 먼저 코드/기존 문서에서 알려진 사실을 확인하고, 이미 답이 있는 질문은 되묻지 않는다.
- `deep-interview`는 라운드마다 가장 큰 미해결 질문 하나를 묻고 Goal, Scope, Constraints, Success, Context를 평가한다. Context는 기존 코드베이스를 변경하는 경우에만 평가한다. 새 프로젝트 가중치는 `.35/.25/.15/.25`, 기존 코드베이스 작업은 `.30/.20/.15/.20/.15` 순서다. 모호성 `<=.20`이며 중요한 미지수가 해결되면 멈춘다. 중요한 dimension이 `<=.50`이어도 핵심 미해결점이 남으면 계속할 수 있다. 응답, 결정, 알려진 사실을 반영하고 다시 brainstorming으로 돌려보낸다.
- `grilling`은 plan/idea/decision 전반의 stress-test이며 아키텍처 전용이 아니다. 사용자의 의미상 stress-test 의도가 있을 때만 조건부 선택한다. skill 절차상 정착된 전체 decision frontier를 매 라운드 질문하므로 `deep-interview`와 혼합/중복하지 않는다. 정확한 skill 이름 언급을 필수 조건으로 오인하지 않는다.
- 한 시점에는 요구 질문 프로세스 하나만 활성화한다. 기존 결정, 열린 질문, acceptance criteria를 재사용하고 이미 답한 질문을 반복하지 않는다.

## Skill Routing by Task Type

| 작업 유형 | 주 흐름 | 조건부 보완 |
|---|---|---|
| 일반 조사/모듈 이해 | 요청된 범위만 조사하고 근거를 보고한다. | 구조 seam 평가가 핵심일 때 `codebase-design`; 설계 loop를 강제하지 않는다. |
| 신규 기능/모호한 요구 | 신규 동작은 `brainstorming`; 모호성이 중요할 때만 `deep-interview` 후 재개. | domain decision이면 `domain-modeling`; 이후 승인된 구현은 계획·단일 실행 경로·TDD를 따른다. |
| 새 모듈/구조 설계 | 새 사용자/동작 선택은 `brainstorming`. | 구조 경계가 실제 주제일 때 `codebase-design`. 기존 dependency를 read-only 검토하는 요청은 `codebase-design` 중심으로 평가하고 구현하지 않는다. |
| Domain 용어/상태 | `domain-modeling`은 실제 domain model 또는 용어를 수정/정의할 때 사용한다. | glossary를 읽기만 하는 요청은 호출 근거가 아니다. ADR은 별도 결정 기록이 필요할 때만 작성한다. |
| API 설계 | `brainstorming`이 system behavior/요구를 맡는다. | `api-and-interface-design`은 contract substage(호환성, 입출력/오류 경계)를 맡는다. 기존 Kotlin/Spring naming과 계약을 바꾸지 않는다. |
| 보안 구현 | 승인된 구현의 단일 실행 경로와 TDD를 적용한다. | 실제 인증/민감정보/외부 trust boundary에서 `security-and-hardening`을 사용한다. |
| Read-only 보안 리뷰 | 해당 범위에 적용 가능한 리뷰 프로세스 하나로 evidence 기반 finding을 보고한다. | `security-and-hardening`은 보안 기준을 보완한다. 리뷰 요청을 자동 수정으로 바꾸지 않는다. |
| 계획 작성 | `writing-plans`; 저장소 PRD/plan 경로와 형식이 기준이다. | 요구 discovery가 미해결일 때만 discovery skill을 먼저 사용한다. Superpowers 전용 중복 계획 폴더를 만들지 않는다. |
| 버그 수정 | 재현 가능한 실패/오류는 `systematic-debugging`으로 원인을 좁힌다. | 구현 시 TDD. 단순 조사/설명만이면 debugging workflow를 강제하지 않는다. |
| 리뷰/피드백 | 요청된 변경은 `requesting-code-review`; 받은 피드백을 실제 반영할 때 `receiving-code-review`. | 중복 full review를 만들지 않고 리뷰 권한만으로 수정하지 않는다. |
| 테스트/완료 검증 | 실패 재현/수정은 TDD; 완료 주장은 `verification-before-completion` 기준의 fresh verification 뒤에 한다. | 프로젝트 focused test 우선순위와 검증 기록 규칙을 유지한다. |
| 기존 작업 이어하기 | 확정된 기존 설계/plan의 첫 미완료 Task를 재개한다. | 새 critical gap만 discovery/planning 재개 사유다. |
| 아키텍처 개선 후보 | 일반 read-only 조사, 구조 평가는 필요 시 `codebase-design`. | `improve-codebase-architecture`는 별도 명시 요청으로 사용자가 선택하기 전 호출하지 않는다. |

- 실제 범위에 맞는 추가 specialist만 선택한다: 화면 구현은 `frontend-ui-engineering`, CI/deploy 변경은 `ci-cd-and-automation`, production telemetry는 `observability-and-instrumentation`, 근거 있는 성능 목표/병목은 `performance-optimization`이다. 이들은 blanket mandatory가 아니다.
- `diagnosing-superpowers`는 superpowers workflow 자체의 장애 분석, `writing-skills`는 skill 작성/수정 때만 선택한다. 일반 개발 기본 체인의 단계가 아니다.

## Conflict and Duplication Resolution

- CORE와 상위 지침, 저장소 규칙, 실제 사용자 범위를 지킨다. stage마다 main owner 하나만 둔다.
- `brainstorming` / `deep-interview`: 새 동작의 선택·설계 대 모호한 요구를 푸는 단일 질문/turn discovery. 설계 main, 큰 unknown이 남을 때만 interview 후 설계로 복귀.
- `brainstorming` / `grilling`: 새 요구를 설계하고 선택하는 흐름 대 확정된 전체 frontier를 압박 시험하는 흐름. 기본 owner는 brainstorming; 의미상 stress-test 필요가 있을 때만 grilling.
- `brainstorming` / `codebase-design`: 제품 동작/요구 선택 대 코드 구조·seam 평가. 새 동작은 brainstorming, 구조 경계만 요청됐으면 codebase-design.
- `codebase-design` / `api-and-interface-design`: 모듈 깊이/seam 대 소비자-facing contract/호환성·오류. 구조 평가는 codebase-design, API skill은 계약 substage만 소유한다.
- `requesting-code-review` / `security-and-hardening`: review process 대 보안 기준. 적용 가능한 단일 review process가 main이고 security skill은 criteria 보완이며 동일 대상을 두 번 full review하지 않는다.
- `systematic-debugging` / general exploration: 재현 가능한 실패의 hypothesis/cause loop 대 read-only code 이해. 실패 재현이면 debugging, 일반 질문이면 조사만 수행한다.
- Domain/구조 어휘 skill은 프로젝트 코드나 공개 contract의 Kotlin/Spring 명명·타입·관례를 rename하거나 덮어쓰지 않는다.

## Automatic Invocation Constraints

- 실행 전에 현재 host의 skill catalog, 설치된 대상 `SKILL.md`와 관련 참조, invocation metadata, host tool permission을 확인한다. 조사 시점의 audit 목록만으로 현재 등록/활성을 단정하지 않는다.
- Codex의 `agents/openai.yaml` `policy.allow_implicit_invocation`, OpenCode의 `metadata["opencode/autoinvoke"]` 및 `skill` allow/ask/deny 권한을 각각 해당 host 문서대로 해석한다. 서로 동등하다고 추정하지 않는다.
- `disable-model-invocation`은 명시적 사용자 의도를 위한 정책 신호다. OpenCode v1이 이 키를 지원한다고 가정하지 않으며, 지원 여부와 무관하게 사용자의 explicit-only 의도를 지킨다.
- `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 catalog에 보여도 explicit-only다. 일반적인 “코드베이스 구조 개선 후보를 찾아줘”는 `improve-codebase-architecture` 호출 승인이 아니다. 사용자가 해당 skill을 명시적으로 이름 붙여 선택해야 한다. setup은 초기 설정을 명시적으로 요청할 때만 실행한다.
- Metadata를 바꾸거나 skill 파일을 읽어 호출 제한을 우회하지 않는다. 제한을 조사하는 것과 skill을 실제 실행하는 것은 다르다.
- Host에서 skill을 찾지 못하거나 권한이 거부되면 한계를 알리고 허용된 프로젝트 절차를 따른다. 존재하지 않는 skill/명령을 가장하거나 직접 설치·생성하지 않는다. Codex Superpowers cache 존재는 activation 증거가 아니다.
- AGENTS 파일의 로딩 계층과 skill 단계 우선순위는 별개다. 이 문서는 플랫폼 instruction loader를 변경하지 않는다. `gstack`은 설치하거나 사용하지 않는다.

## Verification and Completion

- 필요한 문서/도구/참조가 없으면 어느 검토 부분이 미검증인지 보고한다. 공유 checklist 결손을 조용히 무시하거나 global checklist를 만들거나 설치해 full sign-off로 바꾸지 않는다.
- 기존 PRD/plan 경로와 project guides가 변경 범위·테스트·검증 기준이다. 이미 완료된 분석을 다른 skill workflow로 반복하지 않는다.
- 구현 시 focused test부터 시작하고 프로젝트의 TDD, 보안 및 사람 승인 경계를 지킨다. 실패한 테스트를 삭제/완화하지 않는다.
- 새 session은 갱신된 `AGENTS.md`를 안정적으로 다시 읽을 수 있도록 시작한다. skill 단계는 논리적 routing guidance이며 runtime 자동 invocation 성공을 보장하지 않는다.
- worktree는 필요성을 확인하되 자동 생성하지 않는다. branch 종료/merge는 실제 해당 작업일 때만 다루며 commit/push/merge/delete는 명시적 승인 없이는 하지 않는다.
- 사용자가 이미 명확하게 승인한 범위는 다시 묻지 않는다. 승인 경계 밖의 새로운 결정이나 scope 확장만 확인한다.