Files
sodalive-android/AGENTS.md
T

168 lines
13 KiB
Markdown

# AGENTS.md
`SodaLive` 저장소에서 작업하는 에이전트 실행 가이드다.
## 커뮤니케이션 규칙
- **"질문에 대한 답변과 설명과 Todo는 한국어로 한다."**
- 이 저장소에서 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
- 코드 식별자, 경로, 명령어는 원문(영문) 그대로 유지한다.
## CORE EXECUTION PRINCIPLES (andrej-karpathy-skills)
These principles guide project work alongside the applicable harness instructions. System/platform instructions, explicit user requests, and actual permissions take precedence; skill routing below selects workflow roles, not instruction-loading hierarchy.
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는 사용자의 명시적 범위·실행 방식 승인이 있을 때만 허용한다.
- 일반적인 신규 기능·동작 설계의 brainstorming과, 실행을 바꿀 중요한 요구사항이 실제로 모호할 때 필요한 deep-interview는 기본 모드에서 허용한다. 이를 이유로 대규모 변경이나 병렬 작업까지 승인된 것으로 보지 않는다.
### 에이전트 동작 원칙
- 추측하지 말고 근거 파일을 읽고 결정한다.
- 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
## 저장소 범위
- Android Gradle 프로젝트이며 `settings.gradle` 기준 모듈은 `:app` 단일 구성이다.
- 모든 명령은 저장소 루트에서 실행한다.
- 요청 범위를 우선 충족하고, 변경은 작고 안전하게 유지한다.
- 기존 로직 수정이 아닌 신규 `Activity`, `Fragment`, `ViewModel` 및 그와 연결된 하위 코드는 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다.
## 레거시 코드 사용 원칙
- 레거시 코드는 직접 수정하지 않는다.
- 레거시 기능이 필요하면 기존 코드를 호출해서 사용한다.
- 레거시 코드를 약간 변경해야 사용할 수 있는 경우에도 레거시 파일을 고치지 말고, 신규 파일에 wrapper/adapter/확장 코드를 추가해 사용한다.
- 레거시 코드 변경이 불가피해 보이면 구현 전에 사용자에게 확인한다.
## 작업 절차 핵심 규칙
- 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
- 구현 작업 요청을 받으면 먼저 PRD 문서를 작성한다. 일반 질문·읽기 전용 조사는 불필요한 PRD·구현 계획을 새로 만들지 않는다.
- 실행 방향을 바꿀 목표·범위·제약·완료 기준의 중요한 불확실성이 있을 때만 사용자와 인터뷰한다. 코드베이스에서 확인할 수 있는 사실은 직접 조사하고, 이미 명확하거나 승인된 결정은 다시 열지 않는다.
- 인터뷰 내용을 PRD에 반영한 뒤, PRD를 기준으로 계획/TASK 문서를 작성하고 그 문서에 따라 필요한 내용만 최소 구현한다.
- 문서는 `docs/[날짜]_구현할내용한글/` 아래에 `prd.md`, `plan-task.md`로 만든다.
- `docs/[날짜]_구현할내용한글/prd.md`
- `docs/[날짜]_구현할내용한글/plan-task.md`
- 문서 폴더명에서 원래 띄어쓰기가 들어갈 위치는 공백 대신 `_`를 사용한다.
- 예: `docs/20260601_메인_홈_추천_UI와_API_연동/`
- 기존에 생성된 `docs/prd/`, `docs/plan-task/` 문서는 유지하고, 신규 생성 문서부터 위 구조를 적용한다.
- 날짜는 `YYYYMMDD` 8자리 숫자를 사용한다.
- 문서 샘플의 기준 위치는 `docs/sample/`이다.
- PRD 문서는 `docs/sample/sample-prd.md`, 구현 계획/TASK 문서는 `docs/sample/sample-plan-task.md`를 참조해 작업에 필요한 항목을 구체화한다.
- 샘플의 `<...>` placeholder와 예시 값은 실제 작업 값으로 교체한다. 필요한 샘플이 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
- 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다.
- 작업 도중 범위가 변경되면 계획/TASK 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
- 특정 Phase 또는 Task에 직접 대응되는 검증 기록은 해당 Phase 또는 Task 아래에 한국어로 남긴다.
- 여러 Phase에 걸치거나 문서 전체에 해당하는 통합 검증, 회귀 검증, 최종 수동 확인 기록은 문서 최하단 `Verification Log`에 한국어로 남긴다.
- 자동 테스트는 기본적으로 `app/src/test`의 로직/local unit test만 작성하고 실행한다.
- 사용자가 명시적으로 요청하지 않으면 `app/src/androidTest` UI/계측 테스트를 작성하거나 `connectedDebugAndroidTest`, 기기·에뮬레이터 UI 조작, 스크린샷·시각 QA를 실행하지 않는다.
- UI 변경의 테스트 코드는 adapter 분기, mapper, formatter, presentation model, 라우팅처럼 화면 표현을 결정하는 로직만 검증하며 View 크기·간격·constraint·visibility 등 레이아웃 속성을 직접 검증하지 않는다.
- 코드 리뷰, 코드 품질 점검, 완료 Phase 재검토를 수행하면 `docs/sample/sample-review.md`를 참조해 `docs/[날짜]_구현할내용한글/reviews/[리뷰범위]-review.md`에 결과를 기록한다.
- 리뷰 보고서명의 `[리뷰범위]`는 `phase<번호>-<구현 내용을 나타내는 영문 kebab-case>` 형식으로 작성한다. 예: `phase2-main-home-recommendation-review.md`
- 일반 빌드, 테스트, 린트 실행 결과는 리뷰 보고서를 만들지 않고 계획/TASK 문서의 Task별 검증 기록 또는 `Verification Log`에 남긴다.
- 리뷰에서 수정 항목이 확정되면 코드를 수정하기 전에 review ID, 대상 파일, 수정 범위, 회귀 테스트, 완료 증거를 포함한 신규 회귀 수정 Task를 `plan-task.md`의 해당 Phase에 추가하고 그 Task에 따라 바로 수정한다.
- 리뷰 후속 수정 시 기존 완료 Task를 다시 열지 않으며, 기존 완료 체크박스와 검증·리뷰 기록은 삭제하거나 덮어쓰지 않고 위치별로 누적한다.
- 샘플의 위치, 문서 구조, 작성·운용 규칙이 변경되면 같은 작업에서 `AGENTS.md`와 관련 가이드 문서를 함께 갱신한다.
## 상세 참조 문서
- 빌드/린트/테스트는 `docs/agent-guides/build-test-style.md`를 참고한다.
- 코드 스타일/구조는 `docs/agent-guides/code-style.md`를 참고한다.
- 작업 절차/docs/계획 문서 규칙은 `docs/agent-guides/work-plan-docs.md`를 참고한다.
- 커밋 메시지 규칙은 `docs/agent-guides/commit-message-rules.md`를 참고한다.
- 저장소 세부 규칙/보안/Git 안전 수칙은 `docs/agent-guides/safety-repo-rules.md`를 참고한다.
## Agent skills
### 스킬 선택과 작업 단계
- Superpowers가 사용 가능하면 기본 개발 프로세스로 사용한다. 스킬은 작업 유형을 분류한 뒤 프로세스 담당을 먼저 정하고, 필요한 도메인 전문 스킬만 해당 단계에 보완한다. 매 단계 담당은 하나로 유지한다.
- 하네스가 지침을 어떻게 불러오는지는 플랫폼이 정한다. 이 순서는 작업 단계의 역할 순서이며, 자동 선택이나 호출을 보장하지 않는다. 현재 설치된 스킬 정의·메타데이터·권한·호출 가능성을 확인하고, 사용할 스킬의 실제 지침을 읽는다.
- using-superpowers의 진입 지침이 이미 로드되었다면 다시 로드하지 않는다. 명확한 질문·조사는 읽기 전용으로 답한다. 신규 설계는 brainstorming, 구현 전 계획은 writing-plans, 버그는 systematic-debugging 후 test-driven-development(TDD), 구현 단계 테스트는 TDD, 완료 판정은 verification-before-completion, 요청된 코드 리뷰는 requesting-code-review가 담당한다.
- 요구사항 인터뷰는 목표·범위·제약·완료 기준의 중요한 불확실성이 남을 때만 deep-interview로 분리한다. 코드베이스에서 확인할 수 있는 사실은 직접 조사한다. 설계가 승인되었거나 이미 명확하면 다시 열지 않는다.
- 도메인 용어·용어집·ADR 변경은 domain-modeling이 담당한다. 신규 모듈 설계에는 codebase-design, 공개 API 계약에는 api-and-interface-design, 보안 설계·구현·리뷰에는 security-and-hardening을 해당 Superpowers 단계에서 보완한다.
- 기존 의존성 설계 검토는 requesting-code-review와 codebase-design, 개선 후보 탐색은 읽기 전용 조사와 codebase-design으로 한다. grilling은 사용자가 구체적 결정의 스트레스 테스트를 요청하거나 승인된 개선 흐름의 후보를 선택한 경우에만 연결한다.
- improve-codebase-architecture와 setup-matt-pocock-skills는 사용자가 해당 스킬을 명시 선택한 경우에만 실행한다. 일반 아키텍처·설정 요청이나 접근 권한 승인을 명시 호출로 간주하지 않는다.
- 계획 실행은 executing-plans와 subagent-driven-development 중 실제 전제와 승인된 실행 방식에 맞는 하나만 선택한다. 격리·도구·권한·스크립트 전제를 먼저 확인하고 승인 없는 다중 에이전트·커밋·게시를 실행하지 않는다.
- 비구현 작업은 필요한 문서·검증만 적용한다. 후속 작업은 기존 PRD와 계획을 읽고 첫 미완료 Task부터 재개한다.
- 작업 분류, 기본 경로, 스킬 중복, 플랫폼별 호출 제약은 [docs/agents/skill-routing.md](docs/agents/skill-routing.md)를 읽는다. 이 Markdown 링크는 자동 지침 확장이 아니므로 비단순 작업 분류나 역할 중복 해소 시 직접 읽는다.
### Issue tracker
이슈는 `.scratch/<feature-slug>/`의 로컬 Markdown으로 관리한다.
상세 규칙은 `docs/agents/issue-tracker.md`를 참고한다.
### Domain docs
single-context 구조를 사용한다.
상세 규칙은 `docs/agents/domain.md`를 참고한다.
## 핵심 금지사항
- `local.properties`, 키스토어, Google Services 파일, 비밀값은 커밋하거나 외부에 노출하지 않는다.
- `BuildConfig` 값(키/토큰/URL)을 로그, Toast, 크래시 메시지에 직접 노출하지 않는다.
- Git 작업은 비파괴 명령을 기본으로 사용하고, 강제 푸시/히스토리 재작성은 명시 요청이 있을 때만 수행한다.