Instructions
Capy reads AGENTS.md instructions from repositories and Drive.
Instructions for every project
Global instructions live in a drive's root AGENTS.md: Personal for your threads across projects, or Organization for team-wide rules. Both apply within the current organization, outside git.
Add “Use conventional-commit PR titles” to AGENTS.md in my personal drive. Preserve existing instructions.
Drive lets you inspect instruction files by scope alongside other shared files.
How instructions are loaded
Repository instructions load from three sources:
| Source | Files | When it's loaded |
|---|---|---|
| Root instructions | AGENTS.md or CLAUDE.md at the repo root | Thread start |
| Nested instructions | AGENTS.md in any subdirectory | First time the agent touches a file in that directory's subtree |
| Glob rules | .capy/rules/*.{md,mdc}, .cursor/rules/*.{md,mdc} | Thread start if alwaysApply: true, otherwise on first matching file touch |
Root instructions
Every agent reads the repo root's AGENTS.md, falling back to CLAUDE.md when no AGENTS.md exists. Per-agent instruction files (.capy/BUILD.md, .capy/CAPTAIN.md, .capy/REVIEW.md) are deprecated and no longer read; put agent guidance in AGENTS.md, nested files, or glob rules instead.
Nested AGENTS.md
An AGENTS.md anywhere below the repo root is discovered automatically. It isn't loaded at thread start; it's injected into context the first time the agent reads, edits, searches, or lists a file inside that directory's subtree. A thread that never enters packages/api/ never pays the context cost of packages/api/AGENTS.md.
Behavior to know:
- Lazy, then sticky. Each nested file is injected at most once per thread, on first contact with its subtree.
- Deeper wins. When instructions conflict, a more deeply nested
AGENTS.mdtakes precedence over shallower ones (and nested files add to, not replace, the root file). - File tools only. Injection is triggered by file-level operations: reading, editing, searching, and listing files. Shell commands do not trigger nested injection, so a repo-wide grep from the terminal won't pull in every nested file at once.
- Plain markdown. The whole file is treated as instructions. Frontmatter is not parsed; if you need globs or
alwaysApply, use a glob rule instead.
Discovery follows git: only tracked files are found, so anything gitignored never enters context. Root instructions and skill descriptions share one context budget; oversized content is truncated or shortened with a visible marker rather than silently dropped.
Glob rules
Capy reads Cursor-style rules from .capy/rules/ and .cursor/rules/ (.md or .mdc files). YAML frontmatter controls when each rule loads: a rule needs alwaysApply: true or at least one globs pattern to be injected:
---
description: SQL migration conventions
globs:
- "**/*.sql"
alwaysApply: false
---
- Every migration must be reversible
- Never drop columns without an explicit approval commentalwaysApply: trueloads at thread startglobsinjects the first time the agent touches a matching file- Rules are injected with their file path attached, and each rule is injected at most once per thread
Use .capy/rules/ for Capy-native rules; .cursor/rules/ is read natively so existing Cursor setups work unchanged.
Skills
For deep, on-demand workflows (deploy runbooks, codegen procedures, large reference material), use skills instead of instruction files. Skills advertise only their name and description until an agent decides to load one, so they cost almost nothing when unused. Instruction files answer "how should you always behave here?"; skills answer "how do I do this specific thing?".
What goes where
The failure mode to avoid is one giant root file that every thread pays for. Match each piece of guidance to the narrowest mechanism that still reaches it:
| Guidance | Put it in | Why |
|---|---|---|
| Stack summary, build/test/format commands, PR conventions, hard rules | Root AGENTS.md | Every thread needs it |
| Per-package architecture, domain rules, local commands | Nested AGENTS.md in that package | Only loaded when working there |
File-type conventions that cut across directories (**/*.sql, **/*.tsx) | Glob rule | Directory-scoped files can't express "all SQL files" |
| Multi-step workflows, long reference docs | Skill | Loaded on demand, keeps always-on context lean |
Root AGENTS.md carries cross-cutting truths: what the project is, how to install/build/test/lint, commit and PR conventions, and non-negotiable rules ("always use pnpm", "never commit generated files"). Keep it lean: a bloated root file taxes every request in every thread, and long instruction files dilute the agent's attention on the rules that matter.
Nested AGENTS.md carries what's true only inside a subtree. In a monorepo, keep the top-level file general and add a specific AGENTS.md per major subproject: packages/api/AGENTS.md for API conventions, packages/web/AGENTS.md for frontend rules. This is the same layout Amp and other agents recommend, so one set of files serves every tool.
Glob rules carry concerns that follow a file type rather than a directory: design-token rules for every .tsx file, migration rules for every .sql file. If the concern maps cleanly to one directory, prefer a nested AGENTS.md there instead.
Anti-patterns
- Duplicating a rule in multiple files. State it once in the narrowest scope that covers it. Duplicates drift, and the agent has to reconcile conflicting copies.
- Restating what the code already says. Don't enumerate exports, list every directory, or paraphrase type signatures; the agent reads code. Document what it can't infer: intent, invariants, and commands.
- Prompt-sized essays. Ten sharp bullets outperform three pages of prose. "Use pnpm, not npm" beats "please make sure to use the correct package manager for this project".
- Secrets or credentials. Instruction files are injected into model context, and repository instructions are also committed to git. Never put tokens, passwords, or internal URLs that shouldn't leak into them.
- Per-file trivia. "This function retries three times because the upstream API flakes" belongs in a code comment next to the function, not in an instruction file.
Examples
A lean root AGENTS.md
# AGENTS.md
Acme is a TypeScript monorepo: `packages/api` (Fastify + Postgres), `packages/web` (React + Vite), `packages/shared` (types and utils).
## Commands
- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test` (single package: `pnpm --filter @acme/api test`)
- Lint + format: `pnpm check`; run before finishing any task
## Rules
- Always use pnpm, never npm or yarn
- No `any` types; fix type errors instead of suppressing them
- New env vars must be added to `.env.example` and `packages/shared/src/env.ts`
- PR titles follow `type(scope): description` (e.g. `fix(api): handle null user`)A nested packages/api/AGENTS.md
# API package
Fastify server with route handlers in `src/routes/`, business logic in `src/services/`, and data access in `src/db/`.
- Route handlers validate input with zod schemas from `src/schemas/` and stay thin; logic lives in services
- All queries go through the repository layer in `src/db/`; never import the client directly in a route or service
- Every table uses soft deletes (`deleted_at`); filter it in every query
- Integration tests live in `src/__tests__/` and run against the Docker Postgres from `pnpm db:test`A glob rule
---
description: Design token rules for React components
globs:
- "**/*.tsx"
---
- Use tokens from `packages/web/src/styles/tokens.css`, never raw hex colors or arbitrary Tailwind values
- Spacing comes from the `--space-*` scale; font sizes from `text-sm` through `text-2xl` onlyMigrating from other tools
- From Claude Code: nothing required; Capy reads root
CLAUDE.mdas a fallback. To standardize onAGENTS.mdwhile keeping Claude Code working:mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md - From Cursor: keep
.cursor/rules/where it is; Capy reads it natively, includingglobsandalwaysApplyfrontmatter - From other agents using AGENTS.md (Amp, Codex, Devin, ...): nothing required; root and nested
AGENTS.mdfiles work as-is
Changes to repository instruction files apply to the next thread or subagent.