klaus/sodalive-ios
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
44b8633e594b971998172901b086c6947829363b
sodalive-ios/AGENTS.md

7.3 KiB
Raw Blame History

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/**에서 해결한다.
  • 프로젝트 설정 변경은 필요한 경우에만 수행한다.
  • 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를 참조한다.