한국어
문서
규칙

규칙

opencode를 위한 커스텀 지침을 설정하세요.

AGENTS.md 파일을 만들어 opencode에 커스텀 지침을 제공할 수 있습니다. 이는 Cursor의 규칙과 유사합니다. 특정 프로젝트에 맞게 동작을 커스터마이즈하기 위해 LLM의 컨텍스트에 포함될 지침을 담고 있습니다.

초기화

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

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

/init은 저장소의 중요한 파일을 스캔하고, 코드베이스가 답할 수 없는 경우 몇 가지 표적 질문을 할 수 있으며, 그런 다음 간결한 프로젝트별 안내가 담긴 AGENTS.md를 생성하거나 업데이트합니다.

향후 에이전트 세션이 가장 필요로 할 가능성이 높은 것들에 집중합니다:

  • 빌드, 린트, 테스트 명령
  • 명령 순서와, 중요할 때의 집중적인 검증 단계
  • 파일 이름만으로는 명확하지 않은 아키텍처와 저장소 구조
  • 프로젝트별 관례, 설정상의 특이점, 운영상의 함정
  • Cursor 또는 Copilot 규칙 같은 기존 지침 소스에 대한 참조

이미 AGENTS.md가 있는 경우, /init은 이를 무작정 교체하는 대신 그 자리에서 개선합니다.

예시

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

AGENTS.md
# SST v3 Monorepo Project
 
This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
 
## Project Structure
 
- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports
 
## Code Standards
 
- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`
 
## Monorepo Conventions
 
- Import shared modules using workspace names: `@my-app/core/example`

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

유형

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가 없는 경우 사용됨)
  • 스킬 : ~/.claude/skills/ — 자세한 내용은 Agent Skills를 참조하세요

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

export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills

우선순위

opencode가 시작될 때, 다음 순서로 규칙 파일을 찾습니다:

  1. 로컬 파일: 현재 디렉터리에서 위로 탐색(AGENTS.md, CLAUDE.md)
  2. 전역 파일: ~/.config/opencode/AGENTS.md
  3. 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에 중복할 필요 없이 재사용할 수 있습니다.

예시:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}

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

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

외부 파일 참조

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

opencode.json 사용

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

AGENTS.md의 수동 지침

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

AGENTS.md
# TypeScript Project Rules
 
## External File Loading
 
CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
 
Instructions:
 
- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed
 
## Development Guidelines
 
For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md
 
## General Guidelines
 
Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

이 방법으로 다음을 할 수 있습니다:

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

Tip: monorepo 또는 공유 표준을 가진 프로젝트의 경우, glob 패턴(예: packages/*/AGENTS.md)이 있는 opencode.json을 사용하는 것이 수동 지침보다 유지보수하기 더 좋습니다.

도구에이전트