155 lines
7.4 KiB
Markdown
155 lines
7.4 KiB
Markdown
# AGENTS.md
|
|
`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.
|
|
|
|
The following content is taken from the official `andrej-karpathy-skills` `CLAUDE.md` source and is intentionally kept in English.
|
|
|
|
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.
|
|
|
|
## 지시 우선순위
|
|
충돌 시 항상 더 높은 우선순위의 지시를 따른다.
|
|
|
|
1. 사용자 직접 지시
|
|
2. `AGENTS.md`
|
|
3. 프로젝트별 제약 조건
|
|
4. `oh-my-openagent` 플러그인의 `agents` / `workflows` / `hooks`
|
|
5. `superpowers` skills
|
|
6. 기본 모델 동작
|
|
|
|
사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다. plugin / skill / workflow 지시가 `CORE EXECUTION PRINCIPLES`와 충돌하면 `CORE EXECUTION PRINCIPLES`를 따른다. 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
|
|
|
|
## 커뮤니케이션 규칙
|
|
- **"질문에 대한 답변과 설명은 한국어로 한다."**
|
|
- 사용자에게 전달하는 설명, 진행 상황, 결과 보고는 한국어로 작성한다.
|
|
- 코드 식별자, 파일 경로, 명령어는 원문(영문) 그대로 유지한다.
|
|
|
|
## 저장소 범위
|
|
- 앱 소스: `SodaLive/Sources/**`
|
|
- 프로젝트/스킴: `SodaLive.xcodeproj`, `SodaLive.xcworkspace`
|
|
- 의존성 설정: `Podfile`, `Podfile.lock`
|
|
- 운영 스크립트: `work/scripts/**`
|
|
- 생성/외부 결과물: `Pods/**`, `generated/**`, `build/**`
|
|
- 작업 계획 문서: `docs/**`
|
|
|
|
### 수정 우선순위
|
|
- 기능 변경은 `SodaLive/Sources/**`에서 해결한다.
|
|
- 기존 로직 수정이 아닌 신규 `View`, `ViewModel`, `Repository` 및 그와 연결된 하위 코드는 `SodaLive/Sources/V2/**` 아래에 작성한다.
|
|
- 프로젝트 설정 변경은 필요한 경우에만 수행한다.
|
|
- `Pods/**`, `generated/**`는 직접 수정하지 않는다.
|
|
- `build/**`는 빌드 산출물로 간주하며 수정 대상이 아니다.
|
|
|
|
## 실행 모드
|
|
### 기본 모드: 보수적 실행
|
|
- 최소 변경
|
|
- 단순한 구현
|
|
- 검증 가능한 결과
|
|
|
|
### 확장 모드
|
|
- 사용자가 명시적으로 요청한 경우에만 사용한다.
|
|
- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
|
|
|
|
## oh-my-openagent 제어 정책
|
|
- `oh-my-openagent`는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
|
|
- `oh-my-openagent`는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
|
|
- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
|
|
- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
|
|
- 모든 `oh-my-openagent` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
|
|
|
|
## superpowers 사용 정책
|
|
- `superpowers`는 선택적 스킬 계층이다.
|
|
- `superpowers` skill은 필요한 경우에만 사용한다.
|
|
- `superpowers`가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
|
|
- `superpowers`를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
|
|
- 모든 `superpowers` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
|
|
|
|
## 에이전트 동작 원칙
|
|
- 추측하지 말고 근거 파일을 읽고 결정한다.
|
|
- 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
|
|
- 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
|
|
- 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
|
|
- 상세 실행 정책은 `docs/agent-guides/agent-execution-policy.md`를 참조한다.
|
|
|
|
## 개발 세부 가이드
|
|
- 빌드/테스트/검증 명령은 `docs/agent-guides/build-test-verification.md`를 참조한다.
|
|
- iOS 코드 스타일은 `docs/agent-guides/code-style.md`를 참조한다.
|
|
- Cursor/Copilot 규칙은 `docs/agent-guides/sodalive-ios-development.md`를 참조한다.
|
|
- 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다.
|
|
- 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다.
|
|
- 기본 커밋 형식은 `<type>(scope): <description>`를 사용하고, 제목(description)은 한글 명령형/간결한 현재형으로 작성한다.
|
|
- `git commit` 직후 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 확인한다.
|
|
|
|
## 설정/보안 유의사항
|
|
- 토큰/키/개인정보를 코드/로그/문서에 하드코딩하지 않는다.
|
|
- 인증 관련 헤더/토큰 처리 로직(`AuthPlugin`, `UserDefaultsKey.token`) 수정 시 회귀 위험을 함께 점검한다.
|
|
- 외부 SDK 키 변경 시 빌드 설정과 런타임 초기화 지점을 함께 검토한다.
|
|
|
|
## 문서 작성 규칙
|
|
- 구현 전 PRD 작성, 사용자 인터뷰, 계획/TASK 문서 작성, 체크리스트 갱신, 검증 기록 누적, 문서 분리 기준은 `docs/agent-guides/documentation-policy.md`를 따른다.
|
|
|
|
## 문서 유지보수 규칙
|
|
- 상세 문서 유지보수 규칙은 `docs/agent-guides/documentation-policy.md`를 참조한다.
|