sodalive-android/AGENTS.md

AGENTS.md

SodaLive 저장소에서 작업하는 에이전트 실행 가이드다.

실행 우선순위 및 통합 정책

• 충돌 시 아래 우선순위가 높은 지시를 항상 우선 적용한다.
• 우선순위는 다음과 같다.
  1. 사용자 직접 지시
  2. AGENTS.md
  3. 프로젝트별 제약 조건
  4. oh-my-openagent 플러그인의 agents / workflows / hooks
  5. superpowers skills
  6. 기본 모델 동작
• plugin / skill / workflow 지시가 더 낮은 우선순위에 있으면 더 높은 우선순위의 지시를 덮어쓸 수 없다.
• plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)와 충돌하면 CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)를 따른다.
• 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.

커뮤니케이션 규칙

• "질문에 대한 답변과 설명은 한국어로 한다."
• 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
• 코드 식별자, 경로, 명령어는 원문(영문) 그대로 유지한다.

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.

CLAUDE.md

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.

실행 원칙 및 계층 사용 정책

• 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.

기본 모드: 보수적 실행

• 최소 변경
• 단순한 구현
• 검증 가능한 결과

확장 모드

• 사용자가 명시적으로 요청한 경우에만 사용한다.
• 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.

oh-my-openagent 사용 정책

• oh-my-openagent는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
• oh-my-openagent는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
• 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
• 병렬 실행은 명확한 이득이 있을 때만 사용한다.
• 모든 oh-my-openagent 동작은 CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)를 따라야 한다.

superpowers 사용 정책

• superpowers는 선택적 스킬 계층이다.
• superpowers skill은 필요한 경우에만 사용한다.
• superpowers가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
• superpowers를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
• 모든 superpowers 동작은 CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)를 따라야 한다.

에이전트 동작 원칙

• 추측하지 말고 근거 파일을 읽고 결정한다.
• 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
• 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.

저장소 범위

• Android Gradle 프로젝트이며 settings.gradle 기준 모듈은 :app 단일 구성이다.
• 모든 명령은 저장소 루트에서 실행한다.
• 요청 범위를 우선 충족하고, 변경은 작고 안전하게 유지한다.
• 기존 로직 수정이 아닌 신규 Activity, Fragment, ViewModel 및 그와 연결된 하위 코드는 kr.co.vividnext.sodalive.v2 패키지 하위에 작성한다.

작업 절차 핵심 규칙

• PRD 문서와 구현 계획/TASK 문서 없이 구현하지 않는다.
• 사용자의 프롬프트를 받으면 먼저 PRD 문서를 작성하고, 애매하거나 결정이 필요한 내용은 모호함이 사라질 때까지 사용자와 인터뷰한다.
• 인터뷰 내용을 PRD에 반영한 뒤, PRD를 기준으로 계획/TASK 문서를 작성하고 그 문서에 따라 필요한 내용만 최소 구현한다.
• PRD 문서는 docs/prd/, 계획/TASK 문서는 docs/plan-task/ 아래에 둔다.

상세 참조 문서

• 빌드/린트/테스트/코드 스타일은 docs/agent-guides/build-test-style.md를 참고한다.
• 작업 절차/docs/커밋 규칙은 docs/agent-guides/workflow-docs-commits.md를 참고한다.
• 저장소 세부 규칙/보안/Git 안전 수칙은 docs/agent-guides/safety-repo-rules.md를 참고한다.

핵심 금지사항

• local.properties, 키스토어, Google Services 파일, 비밀값은 커밋하거나 외부에 노출하지 않는다.
• BuildConfig 값(키/토큰/URL)을 로그, Toast, 크래시 메시지에 직접 노출하지 않는다.
• Git 작업은 비파괴 명령을 기본으로 사용하고, 강제 푸시/히스토리 재작성은 명시 요청이 있을 때만 수행한다.