# OpenCode Features and Practical Usage 📜 Tired of re-explaining your project's conventions every single session? `AGENTS.md` fixes that: write it once, and the agent always operates with your rules in mind. 🏷️ Title: AGENTS.md 🔗 URL: 📘 Overview `AGENTS.md` is the file you use to give OpenCode custom instructions. Document your project's conventions, architecture, and build steps there, and that content is always included in the LLM's context so the agent behaves the way your team expects. ⚙️ How It Works Rules live at two levels: ・Project-level: an `AGENTS.md` at the repo root, applied only within that directory tree. ・Global-level: `~/.config/opencode/AGENTS.md`, shared across all sessions and best for personal preferences. At startup OpenCode searches in order: local `AGENTS.md` or `CLAUDE.md` (walking up from the current directory) → global `~/.config/opencode/AGENTS.md` → the Claude Code compatibility file `~/.claude/CLAUDE.md`. The first match in each category wins. The design is close to Cursor-style rules and makes migration easy. 🛠️ Practical Usage To pull in external docs as instructions, list them in the `instructions` field of `opencode.json`, e.g. `"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]`. Globs are supported. If writing from scratch feels like a chore, run `/init`: it scans important files, may ask targeted questions, and generates or improves `AGENTS.md` for you. Commit the result to Git so the whole team shares it. 💡 Use Cases Capture tacit knowledge like "commit messages in Japanese," "tests use pytest," or "never import this layer directly" in `AGENTS.md`, and both new teammates and the agent share the same assumptions, cutting down on review churn. In monorepos, `instructions` globs let you bundle per-package conventions. ⚠️ Caveats File references hand-written inside `AGENTS.md` are not expanded automatically. When you need multiple files reliably loaded, the `instructions` field of `opencode.json` is the dependable choice. An existing `CLAUDE.md` is recognized for compatibility, but consolidating new content into `AGENTS.md` keeps things tidy. Remote URL references carry a 5-second timeout. #OpenCode# #AGENTSmd#

# Codex Features and Practical Usage 📝 Stop repeating the same context in every prompt. AGENTS.md is a layered instruction file that teaches Codex your build steps and code conventions for good. 🏷️ Title: Hierarchical Project Instructions (AGENTS.md) 🔗 URL: 📘 Overview AGENTS.md files are persistent instructions Codex reads before starting work. Encode your project norms, build commands, and code standards in Markdown, and Codex automatically discovers and applies them. The defining trait is a layered model where files closer to your current directory take precedence. ⚙️ How It Works Codex builds an instruction chain with strict precedence. ・Global (`~/.codex/`): checks `AGENTS.override.md` first, then `AGENTS.md` ・Project (Git root down to cwd): at each level checks `AGENTS.override.md`, then `AGENTS.md`, then custom fallback names ・Merge: files concatenate from the root downward with blank lines; later files (closer to cwd) override earlier ones It stops adding files once the combined size hits `project_doc_max_bytes` (32 KiB default). Naming conventions: ・`AGENTS.md`: the standard instruction file ・`AGENTS.override.md`: a temporary replacement that takes precedence at its level ・fallback names: configurable via `project_doc_fallback_filenames` (e.g. `TEAM_GUIDE.md`) 🛠️ Practical Usage Split by role for best effect. ・`~/.codex/AGENTS.md` (global): universal personal preferences, e.g. "Always run `npm test` after editing JS," "Prefer `pnpm`" ・repo-root `AGENTS.md`: team norms like linting standards, documentation expectations, and review criteria ・subdirectory `AGENTS.override.md` (e.g. `services/payments/`): override broader rules for a specific domain without deleting parent guidance Verify what loaded by asking Codex to summarize the current instructions, e.g. `codex --ask-for-approval never "Summarize the current instructions."` 💡 Use Cases In a monorepo where only the payments service needs a different test command or review bar, dropping a `services/payments/AGENTS.override.md` switches the rules on only when Codex works under that path. The "Review guidelines" you write here also apply to GitHub's `@/codex review`. ⚠️ Caveats Codex rebuilds the instruction chain on every run, so there is no cache to clear — if guidance looks stale, restart in the target directory. Empty files are skipped and non-existent fallback names are ignored. The `CODEX_HOME` environment variable overrides the default profile location. #OpenAICodex# #AGENTSmd#

One Agents.md/Claude.md rule I find really useful on plan mode: In Plan mode, when the user asks for a revised or new plan after changing the plan, fully rewrite it around the final intended implementation. Do not recap obsolete plan history or include prior revision notes unless the user explicitly asks for that history, because stale process notes can mislead implementation and add redundant work.

Give coding agents room to experiment without putting production data at risk. Lakebase Branching creates isolated, short-lived database environments that capture both schema and data, so agents can test changes without affecting production. Watch how to set up an agentic branching workflow with the Databricks CLI and AGENTS.md, compare changes against the parent branch, and move approved updates through CI/CD.

If you maintain an AGENTS.md or a CLAUDE.md, this one is worth your time. (bookmark it) Researchers traced 94K development events across 557 agentic coding sessions, plus 690K file-level change records from 33K agentic pull requests. Instruction files and working notes account for 60.5% of everything agents read. Classical technical docs get 10.6%. API references get 1.3%. Reading docs is associated with less immediate testing, at an adjusted odds ratio of 0.39. And consultation is self-initiated 70.2% of the time, against 7.5% driven by a failure. In multi-commit agentic pull requests, code gets touched first 4.7x more often. Paper: Track more trending AI papers in our academy:

If you maintain an AGENTS.md or a CLAUDE.md, this is worth a read. (bookmark it) 288 gold-test evaluated runs across Claude Code and Codex, 17 real tasks from 3 repositories, with context-injection strategy as the only variable. Correctness does not move on either agent. Equivalence testing bounds any effect to at most 10 to 15 percentage points. A failure-mode triage explains why. Agents fail on implementation skill, feature design, pattern selection and exact wiring, rather than on repository knowledge a markdown file could supply. A manipulation probe confirms it, since the real AGENTS.md never converted a near-miss into a pass on either agent. Borderline task difficulty is agent-specific with Spearman rho of 0.75, so single-agent studies draw tasks from different informative bands and reach opposite conclusions. That explains a lot of the contradictory prior evidence. Paper: Track more trending AI papers in our academy:

At the top of my AGENTS.md: - NEVER write unit tests after you write code. - Highly prefer E2E tests as the sole testing mechanism. Use them to verify complex features work. At the end of E2E tests, produce a verifiable and repeatable artifact. - If you must test a system in isolation, FIRST write all the ways it could fail, THEN write the code.

Anthropic adds support for the AGENTS․md instructions spec to Claude Code; OpenAI contributed AGENTS․md to the Agentic AI Foundation last year (@thomasclaburn / The Register) (Visit Techmeme dot com for the link and full context!)