OpenCode Agents 가이드: Subagents와 AGENTS.md 7가지 점검

요약: AGENTS.md는 저장소 공통 규칙에 쓰고, OpenCode agents는 전용 프롬프트, 모델, 도구, 안전 경계를 가진 전문 역할에 사용합니다.

AGENTS.md에는 테스트 명령, 코드 스타일, 생성 폴더, 주의 사항처럼 오래 유지되는 저장소 규칙을 둡니다. agent에는 reviewer나 docs-editor 같은 역할별 행동을 둡니다.

두 층을 섞으면 규칙이 중복되고 나중에 충돌하기 쉽습니다.

subagent는 큰 폴더 점검, 위험한 diff 리뷰, API 조사처럼 분리 가능한 관심사가 있을 때 유용합니다.

파일 참조, 패치 계획, 위험 목록처럼 출력 계약을 명확히 하세요.

모델은 역할의 위험도에 맞춥니다. 리뷰와 설계 판단은 더 강한 추론이 필요하고, 요약과 간단한 문서 작업은 가벼운 모델도 충분합니다.

도구와 경로는 필요한 만큼만 열어 우발적 변경을 줄입니다.

공유 설정은 Git에서 검토 가능해야 하지만, 비밀 정보는 환경 변수나 제공자 인증 흐름에 둡니다.

reviewer, docs-editor 같은 안정적인 이름은 로그와 프롬프트를 읽기 쉽게 합니다.

처음에는 쓰기 없이 검증합니다. 범위, 어조, 출력 형식을 확인하세요.

그다음 작은 변경만 허용하고 Git diff를 확인합니다.

1. 역할 이름 정하기reviewer, planner, docs-editor처럼 명확하게 씁니다.
2. 출력 정의하기무엇을 반환하고 무엇을 금지할지 씁니다.
3. 모델 고르기위험도에 추론력과 비용을 맞춥니다.
4. 도구 제한하기필요한 최소 도구부터 시작합니다.
5. 읽기 전용 검증먼저 설명이나 리뷰를 요청합니다.
6. 작은 diff 확인깨끗한 변경 후에만 확대합니다.
7. 규칙 기록언제 agent를 쓸지 문서화합니다.

agents가 너무 많으면 작업 라우팅이 혼란스러워집니다. 반복되는 문제 하나에서 시작하세요.

AGENTS.md와 agent에 같은 규칙을 중복하지 마세요.

MCP, hooks, skills는 역할을 강화하지만 위험 면도 넓힙니다.

프롬프트, 도구, 쓰기 경로를 한 층씩 검증하세요.

{
  "agents": {
    "reviewer": {
      "model": "provider/reasoning-model",
      "description": "Review diffs and return concrete findings only",
      "tools": ["read", "grep"]
    },
    "docs-editor": {
      "model": "provider/fast-model",
      "description": "Update documentation after source changes",
      "tools": ["read", "edit"]
    }
  }
}

공유 설정은 Git에서 검토 가능해야 하지만, 비밀 정보는 환경 변수나 제공자 인증 흐름에 둡니다.