Rules (AGENTS.md)

Bạn có thể cung cấp hướng dẫn tùy chỉnh cho opencode bằng cách tạo file AGENTS.md. Đây tương tự như rules của Cursor. File này chứa các hướng dẫn sẽ được đưa vào context của LLM để tùy chỉnh hành vi cho dự án cụ thể của bạn.

Khởi tạo

Để tạo file AGENTS.md mới, bạn có thể chạy lệnh /init trong opencode.

:::tip Bạn nên commit file AGENTS.md của dự án vào Git. :::

Lệnh này sẽ quét dự án và toàn bộ nội dung để hiểu dự án về gì, sau đó tạo file AGENTS.md tương ứng. Điều này giúp opencode điều hướng dự án tốt hơn.

Nếu bạn đã có sẵn file AGENTS.md, lệnh này sẽ cố gắng bổ sung thêm vào file hiện có.

Ví dụ

Bạn cũng có thể tự tạo file này theo cách thủ công. Đây là ví dụ về những thứ bạn có thể đưa vào file 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`

Chúng ta đang thêm các hướng dẫn cụ thể cho dự án ở đây và nội dung này sẽ được chia sẻ với toàn bộ team.

Các loại Rules

opencode hỗ trợ đọc file AGENTS.md từ nhiều vị trí khác nhau, mỗi vị trí phục vụ mục đích khác nhau.

Project Rules

Đặt file AGENTS.md tại thư mục gốc của dự án cho các rules dành riêng cho dự án đó. Những rules này chỉ áp dụng khi bạn làm việc trong thư mục này hoặc các thư mục con của nó.

Global Rules

Bạn cũng có thể có các rules toàn cục trong file ~/.config/opencode/AGENTS.md. File này được áp dụng cho tất cả các phiên làm việc của opencode.

Vì file này không được commit vào Git hay chia sẻ với team, chúng tôi khuyến nghị sử dụng nó để chỉ định các rules cá nhân mà LLM nên tuân theo.

Tương thích với Claude Code

Đối với người dùng chuyển từ Claude Code sang, OpenCode hỗ trợ các quy ước file của Claude Code như phương án dự phòng:

• Project rules: CLAUDE.md trong thư mục dự án (được sử dụng nếu không có AGENTS.md)
• Global rules: ~/.claude/CLAUDE.md (được sử dụng nếu không có ~/.config/opencode/AGENTS.md)
• Skills: ~/.claude/skills/ — xem Agent Skills để biết chi tiết

Để tắt tính năng tương thích Claude Code, đặt một trong các biến môi trường sau:

export OPENCODE_DISABLE_CLAUDE_CODE=1        # Tắt toàn bộ hỗ trợ .claude
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Chỉ tắt ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Chỉ tắt .claude/skills

Thứ tự ưu tiên

Khi opencode khởi động, nó tìm kiếm các file rules theo thứ tự sau:

1. File cục bộ bằng cách duyệt ngược lên từ thư mục hiện tại (AGENTS.md, CLAUDE.md, hoặc CONTEXT.md)
2. File toàn cục tại ~/.config/opencode/AGENTS.md
3. File Claude Code tại ~/.claude/CLAUDE.md (trừ khi bị tắt)

File đầu tiên khớp sẽ được sử dụng trong mỗi danh mục. Ví dụ, nếu bạn có cả AGENTS.md và CLAUDE.md, chỉ AGENTS.md được sử dụng. Tương tự, ~/.config/opencode/AGENTS.md được ưu tiên hơn ~/.claude/CLAUDE.md.

Custom Instructions

Bạn có thể chỉ định các file hướng dẫn tùy chỉnh trong opencode.json hoặc file toàn cục ~/.config/opencode/opencode.json. Điều này cho phép bạn và team tái sử dụng các rules hiện có thay vì phải sao chép chúng vào AGENTS.md.

Ví dụ:

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

Bạn cũng có thể sử dụng URL từ xa để tải instructions từ web.

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

Các instructions từ xa được fetch với timeout 5 giây.

Tất cả các file instruction được kết hợp với các file AGENTS.md của bạn.

Tham chiếu File bên ngoài

Mặc dù opencode không tự động phân tích các tham chiếu file trong AGENTS.md, bạn có thể đạt được chức năng tương tự theo hai cách:

Sử dụng opencode.json

Cách tiếp cận được khuyến nghị là sử dụng trường instructions trong opencode.json:

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

Hướng dẫn thủ công trong AGENTS.md

Bạn có thể dạy opencode đọc các file bên ngoài bằng cách cung cấp hướng dẫn rõ ràng trong AGENTS.md. Đây là ví dụ thực tế:

# 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.

Cách tiếp cận này cho phép bạn:

• Tạo các file rules có tính module, có thể tái sử dụng
• Chia sẻ rules giữa các dự án qua symlinks hoặc git submodules
• Giữ AGENTS.md ngắn gọn trong khi tham chiếu đến các hướng dẫn chi tiết
• Đảm bảo opencode chỉ tải các file khi cần thiết cho task cụ thể

:::tip Đối với monorepos hoặc dự án có các tiêu chuẩn chung, việc sử dụng opencode.json với glob patterns (như packages/*/AGENTS.md) dễ bảo trì hơn so với hướng dẫn thủ công. :::