OpenCode Rules(AGENTS.md) 사용법: 프로젝트별 ‘AI 작업 규칙’ 표준 세팅하기
AI 코딩 도구를 쓰다 보면 결과물이 들쭉날쭉한 순간이 생깁니다.
어떤 날은 컨벤션을 잘 지키고, 어떤 날은 폴더 구조를 무시하고, 어떤 날은 팀 규칙을 모른 척(?)하죠.
이걸 정리해주는 기능이 OpenCode Rules입니다.
프로젝트에 AGENTS.md 파일을 두면, 그 내용이 LLM 컨텍스트에 포함되어 해당 프로젝트에 맞는 행동 규칙(컨벤션/작업 방식/주의사항)을 계속 유지하도록 도와줘요. (OpenCode)
1) AGENTS.md란?
OpenCode는 AGENTS.md를 “프로젝트 맞춤 지침서”로 사용합니다.
- 팀 컨벤션(코드 스타일, 디렉토리 규칙 등)을 AI에게 지속적으로 적용
- 프로젝트 설명/구조를 미리 알려서 탐색 효율 상승
- 규칙을 팀 단위로 공유(커밋 권장) (OpenCode)
문서에서도 프로젝트의 AGENTS.md는 Git에 커밋하길 권장합니다. 팀 기준을 AI에도 동일하게 적용하겠다는 의미라 체감이 커요. (OpenCode)
2) 빠른 시작: /init으로 자동 생성
처음 만들 때는 OpenCode에서 /init 명령을 실행하면 됩니다.
- 프로젝트와 내용을 스캔해서 “이 프로젝트가 뭔지” 파악
- 그 결과로 AGENTS.md 초안을 생성
- 이미 AGENTS.md가 있으면 기존 파일에 추가를 시도 (OpenCode)
3) AGENTS.md에는 뭘 써야 효과가 좋을까?
문서 예시는 대략 이런 구성입니다:
- 프로젝트 소개(예: 모노레포 / TypeScript / 패키지 매니저)
- 폴더 구조(예: packages/, infra/, 설정 파일 등)
- 코드 스탠다드(예: TypeScript strict)
- 모노레포 컨벤션(예: workspace import 규칙) (OpenCode)
즉, “사람이 새로 투입되면 제일 먼저 알려주는 내용”을 적어두면 AI도 같은 방식으로 움직입니다.
4) Rules 파일 위치 3종: 프로젝트 / 글로벌 / Claude Code 호환
OpenCode는 Rules 파일을 여러 위치에서 읽습니다. 목적이 서로 달라요. (OpenCode)
프로젝트 규칙(Project)
- 프로젝트 루트에 AGENTS.md
- 해당 디렉터리(및 하위)에서만 적용 (OpenCode)
글로벌 규칙(Global)
- ~/.config/opencode/AGENTS.md
- 모든 opencode 세션에 적용
- Git에 커밋되지 않으니 개인 취향/개인 규칙에 추천 (OpenCode)
Claude Code 호환(마이그레이션용 fallback)
- 프로젝트: CLAUDE.md (단, AGENTS.md가 없을 때만)
- 글로벌: ~/.claude/CLAUDE.md (단, ~/.config/opencode/AGENTS.md가 없을 때만) (OpenCode)
그리고 이 호환 기능은 환경변수로 끌 수 있어요. (OpenCode)
- OPENCODE_DISABLE_CLAUDE_CODE=1 : .claude 지원 전체 비활성
- OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 : ~/.claude/CLAUDE.md만 비활성
- OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 : .claude/skills만 비활성
5) “우선순위(Precedence)”가 핵심 포인트
OpenCode는 시작할 때 규칙 파일을 아래 순서로 찾습니다. (OpenCode)
- 현재 디렉터리에서 위로 올라가며 로컬 파일 탐색: AGENTS.md, CLAUDE.md
- 글로벌: ~/.config/opencode/AGENTS.md
- Claude 글로벌: ~/.claude/CLAUDE.md (비활성화하지 않은 경우)
추가로 중요한 룰:
- 같은 카테고리에서는 “먼저 매칭된 파일이 승자”
- 로컬에 AGENTS.md와 CLAUDE.md가 함께 있으면 AGENTS.md만 사용 (OpenCode)
6) AGENTS.md만 쓰지 말고, opencode.json의 instructions로 ‘룰 모듈화’
문서에서 추천하는 방식은 규칙을 여러 파일로 쪼개고 opencode.json의 instructions로 가져오는 방식입니다. (OpenCode)
예시(로컬 파일 + glob 패턴):
- CONTRIBUTING.md
- docs/guidelines.md
- .cursor/rules/*.md (OpenCode)
심지어 원격 URL도 가능하고, 원격은 5초 타임아웃이 걸립니다.
그리고 instructions로 불러온 파일들은 AGENTS.md와 합쳐서 컨텍스트에 들어갑니다. (OpenCode)
팁: 모노레포라면 packages/*/AGENTS.md 같이 glob로 묶는 게 유지보수에 유리하다고 문서에 안내돼요. (OpenCode)
7) 외부 파일 “참조”는 자동 파싱이 아니다(하지만 방법은 2가지)
OpenCode는 AGENTS.md 안에 적힌 파일 참조를 자동으로 파싱하진 않지만, 두 가지 방법으로 같은 효과를 낼 수 있습니다. (OpenCode)
- 권장: opencode.json의 instructions로 필요한 파일을 명시적으로 로드 (OpenCode)
- AGENTS.md에 “파일 참조를 만나면 Read tool로 필요할 때만(lazy loading) 읽어라” 같은 규칙을 직접 적어두기 (OpenCode)
결론: OpenCode Rules는 “AI를 팀원처럼” 만드는 가장 현실적인 방법
AGENTS.md + opencode.json instructions 조합은, 결국 AI에게 우리 팀의 일하는 방식을 학습시키는 최소 비용의 표준화 도구라고 느꼈습니다.
- 프로젝트 구조 설명 반복 ↓
- 컨벤션 지키는 일관성 ↑
- 팀 온보딩(규칙 공유) 쉬움 ↑ (OpenCode)
'AI 코딩도구' 카테고리의 다른 글
| OpenCode CLI 사용법 정리: 터미널에서 opencode를 “명령어처럼” 쓰는 방법 (0) | 2026.02.03 |
|---|---|
| OpenCode 설정(opencode.json) 완전 정리: 어디에 두고, 어떤 키를 쓰면 될까? (1) | 2026.02.03 |
| OpenCode Rules(AGENTS.md) 사용법 총정리: 프로젝트용 “AI 작업 규칙”을 팀 표준으로 만들기 (0) | 2026.02.03 |
| OpenCode Agent Skills 정리: SKILL.md로 에이전트에 ‘재사용 가능한 작업 방식’ 심기 (1) | 2026.02.03 |
| OpenCode MCP 서버 설정 방법 + 써본 후기 (1) | 2026.02.03 |