sodalive-ios/AGENTS.md

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) system/developer 지시와 플랫폼 도구 권한, 2) 사용자의 명시적 요청, 3) 이 저장소의 CORE EXECUTION PRINCIPLES 및 적용 가능한 프로젝트 규칙, 4) 아래 프로젝트 실행 생명주기, 5) 활성화된 전문 스킬의 작업 범위, 6) 플러그인 실행 선호와 기본 모델 동작 순이다. 상위 역할의 지시와 도구 권한을 Markdown으로 변경하거나 우회하지 않는다. 사용자 요청도 상위 지시 및 도구 권한을 넘을 수 없다.

프로젝트가 통제하는 절차에서는 Superpowers가 주 생명주기이며, 전문 스킬은 해당 단계의 좁은 전문 영역을 맡는다. 플러그인은 도구와 실행 보조를 제공할 뿐 별도의 경쟁 절차를 만들지 않는다. 플러그인에 주입된 상위 역할 지시는 이 문서로 덮어쓸 수 없다. 불확실하면 근거를 확인하고 최소 안전 범위에서 진행한다.

커뮤니케이션 규칙

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

저장소 범위

• 앱 소스: SodaLive/Sources/**
• 프로젝트/스킴: SodaLive.xcodeproj, SodaLive.xcworkspace
• 의존성 설정: Podfile, Podfile.lock
• 운영 스크립트: work/scripts/**
• 생성/외부 결과물: Pods/**, generated/**, build/**
• 작업 계획 문서: docs/**

수정 우선순위

• 기능 변경은 SodaLive/Sources/**에서 해결한다.
• 기존 로직 수정이 아닌 신규 View, ViewModel, Repository 및 그와 연결된 하위 코드는 SodaLive/Sources/V2/** 아래에 작성한다.
• 여러 페이지에서 재사용 가능한 공용 컴포넌트는 SodaLive/Sources/V2/Component/** 아래에 형태별 폴더(Card, Banner, Text, Button, Creator 등)로 배치한다.
• 특정 페이지 내부에서만 사용하는 컴포넌트는 해당 페이지 폴더 하위 Components에 배치한다.
• 프로젝트 설정 변경은 필요한 경우에만 수행한다.
• Pods/**, generated/**는 직접 수정하지 않는다.
• build/**는 빌드 산출물로 간주하며 수정 대상이 아니다.

실행 모드

기본 모드: 보수적 실행

• 최소 변경
• 단순한 구현
• 검증 가능한 결과
• 요청이 구체적이면 불필요한 인터뷰 없이 관련 생명주기의 첫 미완료 단계부터 시작한다.

확장 모드

• 대규모 리팩터링, 다중 에이전트 실행, 병렬 workflow 확장은 사용자가 명시적으로 허용한 경우에만 한다. 작은 작업은 단일 경로로 처리한다.

Skill Orchestration

작업을 시작할 때 질문/조사, 신규 설계, 불명확한 요구사항, 버그, 아키텍처, API, 보안, 리뷰, 테스트/검증, 기존 작업 이어하기 중 하나 이상으로 분류한다. 활성 하위 단계마다 주 소유 스킬 하나를 정하고, 필요한 좁은 보완 스킬만 추가한다. 현재 호스트에서 발견·접근 가능한 스킬만 사용하고, implicit 선택이 허용된 경우에도 deny/ask 및 agent/tool 권한을 준수한다. 스킬이 없거나 접근이 막히면 한계를 알리고 가능한 부분만 수행한다. 호스트가 현재 해석한 설치 스킬 본문을 먼저 읽는다. 이미 로드된 동일 본문과 끝난 질문·계획·리뷰 결과는 재사용하며 되풀이하지 않는다. 일반 질문·조사·문서 작업은 제품 구현 생명주기를 자동 시작하지 않는다.

작업	주 생명주기와 선택 스킬
새 기능/설계	Superpowers brainstorming으로 설계. 필요할 때만 deep-interview, domain-modeling, codebase-design을 좁게 보완한다.
요구사항이 중요하게 미정	임시 소유자 deep-interview; 아래 종료 기준을 만족하면 요약을 기존 PRD에 통합하고 설계 단계로 이동한다.
도메인 용어/사업 모델 변경	실제 용어집 또는 도메인 모델 변경이면 domain-modeling; 단순 조회에는 호출하지 않는다.
REST/API 설계	brainstorming 설계 단계 안에서 api-and-interface-design으로 계약을 구체화하고, 인증/신뢰 경계가 관련되면 security-and-hardening을 보완한다.
버그	systematic-debugging → 재현 회귀 테스트/TDD → 단일 실행 경로 → 해당 시 requesting-code-review → verification-before-completion.
아키텍처 검토	목적에 맞는 읽기 전용 분석. 구체적 대안 설계는 codebase-design; 별도 사용자 요청 없이는 HTML/그릴 워크플로를 자동 호출하지 않는다.
계획	writing-plans. 승인된 설계와 유효한 계획이 함께 있으면 첫 미완료 단계부터 이어가고, 설계만 확정됐다면 새 인터뷰 없이 빠진 계획만 작성한다.
계획 실행	executing-plans 또는 subagent-driven-development 중 하나만 사용한다. 실제 도구가 지원하고 사용자가 고른 방법 및 독립성에 맞춘다. 둘을 중첩하지 않는다.
구현 테스트 단계	test-driven-development; 버그 경로에서는 systematic-debugging이 진단을 소유하고 TDD는 회귀 테스트 단계만 맡는다.
코드 리뷰/피드백	완료된 작업의 단일 리뷰는 requesting-code-review; 보안 기준이 필요하면 범위를 좁혀 보완한다. 받은 피드백의 기술적 평가는 receiving-code-review.
CI/CD, UI, 운영성, 성능	실제 pipeline 변경에는 ci-cd-and-automation, UI/accessibility 작업에는 frontend-ui-engineering, telemetry에는 observability-and-instrumentation, 측정된 bottleneck에는 performance-optimization을 조건부 보완으로 사용한다.
검증/통합	완료 주장 전 verification-before-completion. finishing-a-development-branch는 통합이 실제 범위일 때만 사용하며, 요청 없는 commit/push/정리를 하지 않는다.
격리/병렬 읽기	실제 구현 경로가 필요할 때 기존/native 격리 수단을 먼저 확인하는 using-git-worktrees. 독립 읽기 트랙 병렬화는 허용된 경우에만 dispatching-parallel-agents; SDD 구현자를 별도로 병렬 중첩하지 않는다.

deep-interview는 목표, 범위, 제약, 성공 기준, 맥락 중 중요한 미해결 사항이 있거나 해석이 충돌/핵심 조건이 빠졌거나 사용자가 명시한 경우에만 잠시 소유한다. 질문은 한 번에 하나씩 한다. 해당 점수법에서 전체 불확실성 0.20 이하뿐 아니라 모든 중요한 결정이 해결되어야 종료하며, 중요한 차원 하나라도 0.50 이하로 충분히 확정되지 않으면 계속한다. 해결된 문제를 반복 인터뷰하지 않는다. 이 스킬은 산출물/의존성을 정하지 않는다. 자동 .scratch나 별도 명세를 만들지 말고 요약을 기존 PRD에 반영한다.

grilling은 계획·결정·아이디어 전반에 대한 스트레스 테스트이며 아키텍처 전용이 아니다. 사용자가 원하거나 구체적인 아키텍처 대안을 비교할 때 주로 쓴다. 회차마다 의존 조건이 해결된 질문을 묶어 묻고 답변을 기다리며, 종료 시 사용자의 공유 이해 확인을 받는다. 그릴의 다중 질문 회차와 다른 스킬의 한 번에 하나 질문 규칙을 동시에 적용하지 않는다. codebase-design은 모듈 규모와 무관한 depth/seam/locality 및 exposed interface를 다루고, api-and-interface-design은 내부·외부 API 계약의 안정성/errors/compatibility를 다룬다. 두 skill을 internal/public로만 나누지 않는다. 둘 다 별도의 전체 설계나 인터뷰 절차를 대체하지 않는다.

자동 선택과 실행 경계

• Codex 스킬 자동 호출은 설치 정의의 agents/openai.yaml policy.allow_implicit_invocation: false로 막을 수 있다(기본값은 true). 명시적 호출은 별개다.
• OpenCode의 metadata['opencode/autoinvoke']='false'는 모델 자동 선택 노출을 숨기지만 직접 호출을 막지 않는다. permission.skill의 deny/ask와 agent/tool 권한은 별도 제어다. disable-model-invocation은 OpenCode의 문서화된 동등 설정이 아니다.
• improve-codebase-architecture와 setup-matt-pocock-skills는 disable-model-invocation: true 및 Codex implicit false가 있다. OpenCode autoinvoke metadata는 없어 광고될 수 있다. 프로젝트 정책상 명시 전용이지만 Markdown이 OpenCode backend/hook 차단을 강제하는 것은 아니다. “기존 코드 구조 개선 후보 찾기”나 일반 HTML 요청만으로 실행하지 않는다. 사용자가 skill 이름으로 명시 호출한 경우에만 그 workflow를 고려하며, 요청 범위를 넘어 HTML 생성/브라우저 열기/grilling을 흉내 내지 않는다. 허용된 읽기 전용 codebase-design 분석은 별개다. setup-matt-pocock-skills는 별도 일회성 명시 요청에만 쓴다.
• 빠진 스킬이나 필수 참고 파일이 있으면 한계를 알리고 가능한 부분 확인만 한다. 완전한 절차를 수행했다고 주장하지 않는다. 스킬 설치나 메타데이터 변경으로 제한을 우회하지 않는다. gstack은 어느 단계에서도 사용하거나 설치하지 않는다.
• 웹 대상 스킬의 예시는 적용 가능한 통제만 참고한다. iOS 코드에 서버 cookie/CSP 등을 옮겨 적용하지 않으며 SodaLive의 실제 API와 스타일을 따른다.

에이전트 동작 원칙

• 추측하지 말고 근거 파일을 읽고 결정한다.
• 기존 관례를 깨는 변경은 이유가 명확할 때만 수행한다.
• 불필요한 리팩터링 확장은 피하고 요청 범위를 우선 충족한다.
• 결과 보고 시 무엇을, 왜, 어떻게 검증했는지 한국어로 간단히 남긴다.
• 상세 실행 정책은 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를 단일 기준으로 사용한다.
• 커밋 작업 시작 시 commit-policy를 먼저 로드한다. OpenCode에서는 skill 도구를 사용하고, Codex에서는 발견된 SKILL.md 또는 .opencode/skills/commit-policy/SKILL.md를 읽는다.
• 기본 커밋 형식은 <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를 따른다.
• 신규 PRD, 계획/TASK 문서, 코드 리뷰 리포트를 만들기 전에 각각 docs/sample/sample-prd.md, docs/sample/sample-plan-task.md, docs/sample/sample-review.md를 확인하고 현재 샘플 구조를 따른다.
• 연속된 하나의 작업은 새 문서를 만들지 말고 기존 PRD와 plan-task.md에 이어서 기록한다.
• 계획/TASK 문서는 sample-plan-task.md의 Phase, Task, Goal, 완료 증거, 검증 기록 구조를 따르고 각 Task에 대상 파일 경로와 검증 기준을 적는다.
• 코드 리뷰와 점검 결과는 PRD 및 plan-task.md와 같은 작업 디렉터리의 reviews/ 아래에 phase<번호>-<구현 내용을 나타내는 영문 kebab-case>.md 형식의 리포트로 남긴다.
• 리뷰에서 수정이 필요하다고 확정한 항목은 코드 수정 전에 plan-task.md의 해당 Phase에 실행 가능한 신규 Task로 추가하고, 그 Task를 기준으로 수정 및 검증한다.

문서 유지보수 규칙

• 상세 문서 유지보수 규칙은 docs/agent-guides/documentation-policy.md를 참조한다.
• docs/sample/**의 경로 또는 구조가 바뀌면 AGENTS.md, docs/agent-guides/**, 샘플 간 참조를 함께 갱신해 서로 일치시킨다.

Agent skills

Issue tracker

로컬 Markdown으로 .scratch/<feature-slug>/에서 이슈를 관리한다. 세부 규칙은 docs/agents/issue-tracker.md를 따른다.

Domain docs

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