규칙

opencode에 대한 사용자 정의 지침을 설정합니다.

AGENTS.md 파일을 생성하여 opencode에 사용자 정의 지침을 제공할 수 있습니다. 이는 Cursor의 rules와 유사합니다. 특정 프로젝트에 맞게 동작을 커스터마이징하기 위해 LLM의 컨텍스트에 포함될 지침이 들어 있습니다.

초기화

새 AGENTS.md 파일을 생성하려면 opencode에서 /init 명령을 실행할 수 있습니다.

팁: 프로젝트의 AGENTS.md 파일을 Git에 커밋해야 합니다.

이렇게 하면 프로젝트와 모든 내용을 스캔하여 프로젝트가 무엇에 관한 것인지 이해하고 AGENTS.md 파일을 생성합니다. 이는 opencode가 프로젝트를 더 잘 탐색하는 데 도움이 됩니다.

기존 AGENTS.md 파일이 있는 경우 추가하려고 시도합니다.

예제

이 파일을 수동으로 만들 수도 있습니다. 다음은 AGENTS.md 파일에 넣을 수 있는 몇 가지 예입니다.

여기에 프로젝트별 지침을 추가하고 있으며 이는 팀과 공유됩니다.

유형

opencode는 여러 위치에서 AGENTS.md 파일을 읽는 것도 지원합니다. 이는 다양한 목적을 위한 것입니다.

프로젝트

프로젝트별 규칙을 위해 프로젝트 루트에 AGENTS.md를 배치합니다. 이 디렉토리 또는 하위 디렉토리에서 작업할 때만 적용됩니다.

전역

~/.config/opencode/AGENTS.md 파일에 전역 규칙을 가질 수도 있습니다. 이는 모든 opencode 세션에 적용됩니다.

이것은 Git에 커밋되거나 팀과 공유되지 않으므로 LLM이 따라야 할 개인 규칙을 지정하는 데 사용하는 것이 좋습니다.

Claude Code 호환성

Claude Code에서 마이그레이션하는 사용자를 위해 OpenCode는 Claude Code의 파일 규칙을 폴백으로 지원합니다:

• 프로젝트 규칙: 프로젝트 디렉토리의 CLAUDE.md (AGENTS.md가 없는 경우 사용)
• 전역 규칙: ~/.claude/CLAUDE.md (~/.config/opencode/AGENTS.md가 없는 경우 사용)
• Skills: ~/.claude/skills/ — 자세한 내용은 Agent Skills를 참조하세요

Claude Code 호환성을 비활성화하려면 다음 환경 변수 중 하나를 설정하세요:

우선순위

opencode가 시작되면 다음 순서로 규칙 파일을 찾습니다:

• 로컬 파일 현재 디렉토리에서 위로 탐색 (AGENTS.md, CLAUDE.md)
• 전역 파일 ~/.config/opencode/AGENTS.md에서
• Claude Code 파일 ~/.claude/CLAUDE.md에서 (비활성화되지 않은 경우)

각 카테고리에서 첫 번째로 일치하는 파일이 우선합니다. 예를 들어 AGENTS.md와 CLAUDE.md가 모두 있으면 AGENTS.md만 사용됩니다. 마찬가지로 ~/.config/opencode/AGENTS.md가 ~/.claude/CLAUDE.md보다 우선합니다.

사용자 정의 지침

opencode.json 또는 전역 ~/.config/opencode/opencode.json에서 사용자 정의 지침 파일을 지정할 수 있습니다. 이를 통해 팀이 AGENTS.md에 복제하는 대신 기존 규칙을 재사용할 수 있습니다.

예:

웹에서 지침을 로드하기 위해 원격 URL을 사용할 수도 있습니다.

원격 지침은 5초 타임아웃으로 가져옵니다.

모든 지침 파일은 AGENTS.md 파일과 결합됩니다.

외부 파일 참조

opencode는 AGENTS.md의 파일 참조를 자동으로 파싱하지 않지만 두 가지 방법으로 유사한 기능을 달성할 수 있습니다:

opencode.json 사용

권장되는 접근 방식은 opencode.json의 instructions 필드를 사용하는 것입니다:

AGENTS.md의 수동 지침

AGENTS.md에 명시적인 지침을 제공하여 opencode가 외부 파일을 읽도록 가르칠 수 있습니다. 다음은 실용적인 예입니다:

이 접근 방식을 통해 다음을 수행할 수 있습니다:

• 모듈식, 재사용 가능한 규칙 파일 생성
• symlink 또는 git 서브모듈을 통해 프로젝트 간 규칙 공유
• 상세한 가이드라인을 참조하면서 AGENTS.md를 간결하게 유지
• opencode가 특정 작업에 필요할 때만 파일을 로드하도록 보장

팁: 모노레포 또는 공유 표준이 있는 프로젝트의 경우 glob 패턴과 함께 opencode.json을 사용하는 것(예: packages/*/AGENTS.md)이 수동 지침보다 유지 관리가 더 쉽습니다.