@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-agent-instructions-analyze/references/docs/rules-files.md

@@ -0,0 +1,594 @@
+# Rules and Instruction Files — Cross-Provider Deep Dive
+
+> Research synthesis compiled 2026-02-19 from official provider documentation.
+> For provider-specific links, see [provider-reference.md](./provider-reference.md).
+> For the generalized instruction file playbook, see [agent-instruction.md](./agent-instruction.md).
+
+---
+
+## Table of Contents
+
+1. [What This Document Covers](#1-what-this-document-covers)
+2. [Claude Code](#2-claude-code)
+3. [Cursor](#3-cursor)
+4. [GitHub Copilot](#4-github-copilot)
+5. [Cross-Provider Comparison](#5-cross-provider-comparison)
+6. [Quantitative Data: Sizes, Limits, Token Budgets](#6-quantitative-data-sizes-limits-token-budgets)
+7. [Context Engineering Principles](#7-context-engineering-principles)
+8. [Best Practices (Cross-Provider Consensus)](#8-best-practices-cross-provider-consensus)
+9. [Anti-Patterns](#9-anti-patterns)
+10. [Portability Strategy](#10-portability-strategy)
+11. [Sources](#11-sources)
+
+---
+
+## 1. What This Document Covers
+
+This document provides a deep, provider-specific reference for **rules files and instruction files** — the mechanisms each tool uses to give persistent, scoped context to AI coding agents. It complements `agent-instruction.md` (the generalized playbook) by going deeper into how each tool actually works.
+
+**Scope:** Claude Code rules & memory, Cursor rules, Copilot instructions. Copilot is included here (rather than only in agent-instruction.md) because its scoped instruction files (`.instructions.md` with `applyTo` globs) function more like rules than like traditional agent instructions — they activate conditionally based on file patterns, just like Claude's path-scoped rules and Cursor's glob-attached rules.
+
+**Out of scope:** Skills, subagents, hooks, plugins (see their respective guides).
+
+---
+
+## 2. Claude Code
+
+### 2.1 File Hierarchy
+
+Source: [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) (official)
+
+Claude Code loads instruction files from a 6-level hierarchy:
+
+| Memory Type        | Location                                                                                        | Purpose                                             | Shared With      |
+| ------------------ | ----------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------- |
+| **Managed policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`; Linux: `/etc/claude-code/CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | All users in org |
+| **Project memory** | `./CLAUDE.md` **or** `./.claude/CLAUDE.md`                                                      | Team-shared instructions for the project            | Team (git)       |
+| **Project rules**  | `./.claude/rules/*.md`                                                                          | Modular, topic-specific project instructions        | Team (git)       |
+| **User memory**    | `~/.claude/CLAUDE.md`                                                                           | Personal preferences for all projects               | Just you         |
+| **Project local**  | `./CLAUDE.local.md`                                                                             | Personal project-specific preferences               | Just you         |
+| **Auto memory**    | `~/.claude/projects/<project>/memory/`                                                          | Claude's automatic notes and learnings              | Just you         |
+
+Both `./CLAUDE.md` and `./.claude/CLAUDE.md` are valid project memory locations. `CLAUDE.local.md` is automatically gitignored.
+
+### 2.2 Discovery and Loading
+
+**Upward recursion at launch:**
+
+> "Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory `/` and reads any CLAUDE.md or CLAUDE.local.md files it finds."
+
+**Downward discovery on demand:**
+
+> "Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees."
+
+- **Loaded at launch:** All CLAUDE.md files in the directory hierarchy **above** the working directory
+- **Loaded on demand:** CLAUDE.md files in **child** directories, only when Claude reads files there
+- **Auto memory:** First 200 lines of `MEMORY.md` loaded at startup; topic files read on demand
+
+The `--add-dir` flag gives Claude access to extra directories. CLAUDE.md from those dirs is NOT loaded unless `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set.
+
+### 2.3 @-Import Syntax
+
+CLAUDE.md files can import additional files using `@path/to/import`:
+
+```markdown
+@AGENTS.md
+@docs/git-instructions.md
+@~/.claude/my-project-instructions.md
+```
+
+Key behaviors:
+
+- Relative paths resolve **relative to the file containing the import**, not the working directory
+- Absolute and `@~/` home paths supported
+- Recursive imports supported, **max depth of 5 hops**
+- NOT evaluated inside markdown code spans or code blocks
+- First-time imports trigger a one-time approval dialog per project (cannot be re-prompted if declined)
+- For worktrees: use `@~/.claude/my-project-instructions.md` since `CLAUDE.local.md` only exists in one worktree
+
+### 2.4 Override and Merge Semantics
+
+> "More specific instructions take precedence over broader ones."
+
+Precedence (highest to lowest):
+
+1. **Managed policy** (cannot be overridden)
+2. **Project rules** (`.claude/rules/*.md`) — same priority as `.claude/CLAUDE.md`
+3. **Project memory** (`./CLAUDE.md`)
+4. **User memory** (`~/.claude/CLAUDE.md`)
+5. **Project local** (`./CLAUDE.local.md`)
+6. **Auto memory**
+
+> "User-level rules are loaded before project rules, giving project rules higher priority."
+
+Settings precedence is separate: Managed > CLI args > Local > Project > User. Permission evaluation: deny first, then ask, then allow. First matching rule wins.
+
+### 2.5 Modular Rules (`.claude/rules/`)
+
+All `.md` files in `.claude/rules/` are automatically loaded as project memory. Subdirectories are fully supported and recursively discovered. Symlinks are supported; circular symlinks handled gracefully.
+
+**Unconditional rules** (no frontmatter) load on every session.
+
+**Conditional rules** use `paths` frontmatter — the only documented frontmatter field for rules:
+
+```yaml
+---
+paths:
+  - 'src/api/**/*.ts'
+  - 'src/**/*.{ts,tsx}'
+---
+# API Development Rules
+- All API endpoints must include input validation
+```
+
+User-level rules go in `~/.claude/rules/` and apply to all projects (lower priority than project rules).
+
+### 2.6 AGENTS.md Support
+
+**AGENTS.md is NOT natively supported by Claude Code** (GitHub issue #6235 has 2,700+ upvotes, still open). The recommended workaround is a one-line `CLAUDE.md`:
+
+```markdown
+@AGENTS.md
+```
+
+This leverages @-import. Alternative: symlink `ln -s AGENTS.md CLAUDE.md`.
+
+### 2.7 Skills vs CLAUDE.md vs Rules
+
+Source: [code.claude.com/docs/en/best-practices](https://code.claude.com/docs/en/best-practices) (official)
+
+| Mechanism            | Always loaded    | On-demand    | Best for                                       |
+| -------------------- | ---------------- | ------------ | ---------------------------------------------- |
+| **CLAUDE.md**        | Yes              | No           | Broad project conventions loaded every session |
+| **Rules (no paths)** | Yes              | No           | Focused topic files always relevant to project |
+| **Rules (w/ paths)** | No               | Yes          | File-type-specific conventions                 |
+| **Skills**           | Description only | Full content | Domain knowledge, reusable workflows, tasks    |
+| **Auto memory**      | 200 lines        | Rest         | Claude's own learnings and project patterns    |
+
+> "CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead."
+
+---
+
+## 3. Cursor
+
+### 3.1 Rule Types
+
+Source: [cursor.com/docs/context/rules](https://cursor.com/docs/context/rules) (official)
+
+Rules provide system-level instructions to Cursor's Agent:
+
+> "Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level."
+
+> "Rule contents are included at the start of the model context."
+
+### 3.2 File Format (.mdc)
+
+Cursor supports `.md` and `.mdc` extensions:
+
+> "Use `.mdc` files with frontmatter to specify `description` and `globs` for more control over when rules are applied."
+
+```yaml
+---
+description: 'Python coding guidelines for backend services'
+alwaysApply: false
+globs: ['src/**/*.ts', 'lib/**/*.ts']
+---
+# Rule Title
+Rule content in markdown format.
+```
+
+Rules support `@filename.ts` syntax to reference files without duplicating content.
+
+### 3.3 Frontmatter Fields — Complete Reference
+
+The official documentation defines **three** frontmatter fields:
+
+| Field         | Type               | Purpose                                                |
+| ------------- | ------------------ | ------------------------------------------------------ |
+| `description` | string             | Concise explanation; used by Agent to decide relevance |
+| `alwaysApply` | boolean            | When `true`, rule included in every session            |
+| `globs`       | string or string[] | File patterns for auto-attachment                      |
+
+**Activation mode is derived from the combination:**
+
+| Configuration                                   | Resulting Mode                                           |
+| ----------------------------------------------- | -------------------------------------------------------- |
+| `alwaysApply: true`                             | **Always** — included in every session                   |
+| `alwaysApply: false` + `globs` set              | **Auto Attached** — included when matching files appear  |
+| `alwaysApply: false` + `description` (no globs) | **Agent Requested** — Agent decides based on description |
+| No frontmatter / none set                       | **Manual** — user must @-mention the rule                |
+
+> **Note:** `agentRequested` and `manual` are NOT official frontmatter fields — those behaviors are achieved through combinations of the three real fields above.
+
+### 3.4 Rule Scopes
+
+**Project Rules:** `.cursor/rules/` directory, version-controlled, supports subdirectories.
+
+**User Rules:** Configured in **Cursor Settings** UI (Settings > General > Rules for AI). NOT file-system-based — there is no `~/.cursor/rules/` directory. Apply only to Agent (Chat), not to Inline Edit or Cursor Tab.
+
+**Team Rules:** Dashboard-managed, available on Team/Enterprise plans. Can be enforced to prevent user disabling.
+
+### 3.5 AGENTS.md — First-Class Support
+
+Cursor natively reads AGENTS.md:
+
+> "AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to `.cursor/rules`."
+
+Nested AGENTS.md in subdirectories is supported with hierarchical precedence (more specific wins).
+
+| Aspect             | AGENTS.md                 | .cursor/rules         |
+| ------------------ | ------------------------- | --------------------- |
+| Format             | Plain markdown            | .mdc with frontmatter |
+| Activation control | Always on                 | Four activation modes |
+| Glob targeting     | No                        | Yes                   |
+| Cross-tool compat  | Yes (Claude, Codex, etc.) | Cursor-specific       |
+
+### 3.6 Precedence
+
+> "Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts."
+
+### 3.7 Legacy .cursorrules
+
+> "The `.cursorrules` (legacy) file in your project root is still supported but will be deprecated. We recommend migrating to Project Rules or to AGENTS.md."
+
+### 3.8 Cursor 2.2+ Folder Format (RULE.md)
+
+Source: community references (not confirmed in primary official docs)
+
+As of Cursor 2.2, new rules are created as folders: `.cursor/rules/<name>/RULE.md`. Legacy `.mdc` files continue to work. This is the Cursor UI's default for _new_ rules, not a change to how rules are read.
+
+### 3.9 Notepads vs Rules
+
+| Aspect          | Rules                                        | Notepads                      |
+| --------------- | -------------------------------------------- | ----------------------------- |
+| Activation      | Automatic (various modes)                    | Manual (@-reference only)     |
+| Storage         | File system (`.cursor/rules/`)               | Cursor UI (Explorer sidebar)  |
+| Version control | Yes (project rules)                          | No — local to Cursor instance |
+| Team sharing    | Via repo (project) or dashboard (team)       | Not shareable                 |
+| Token usage     | Always-on rules consume tokens every session | Only when referenced          |
+
+Use rules for standards that should apply automatically. Use notepads for on-demand reference material.
+
+### 3.10 Limitations
+
+Rules only apply to **Agent (Chat)**. They do NOT affect:
+
+- Cursor Tab (autocomplete suggestions)
+- Inline Edit (Cmd/Ctrl+K) — for user rules specifically
+- Other AI features beyond Agent
+
+---
+
+## 4. GitHub Copilot
+
+### 4.1 Repository-Level Instructions
+
+Source: [docs.github.com](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) (official)
+
+**File:** `.github/copilot-instructions.md` — always-on, automatically included in every chat request.
+
+> "The instructions in the file(s) are available for use by Copilot as soon as you save the file(s). Instructions are automatically added to requests that you submit to Copilot."
+
+Format: plain Markdown. Whitespace between instructions is ignored. VS Code `/init` command can auto-generate this file. Recommended max: **~1,000 lines**.
+
+### 4.2 Scoped Instruction Files
+
+**Pattern:** `.github/instructions/<NAME>.instructions.md` — activated by file pattern matching (similar to Claude rules and Cursor glob rules).
+
+**Frontmatter — all supported fields:**
+
+| Field          | Required | Description                                                                              |
+| -------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `applyTo`      | No       | Glob pattern(s), comma-separated. Relative to workspace root.                            |
+| `description`  | No       | Short description shown on hover (VS Code). Enables semantic matching when no `applyTo`. |
+| `name`         | No       | Display name in UI (VS Code). Defaults to filename.                                      |
+| `excludeAgent` | No       | Prevents use by a specific agent. Values: `"code-review"` or `"coding-agent"`.           |
+
+```yaml
+---
+applyTo: '**/*.ts,**/*.tsx'
+excludeAgent: 'code-review'
+---
+When writing TypeScript code in this repository...
+```
+
+Scoped instructions are **additive** — they combine with (not replace) the main `copilot-instructions.md`:
+
+> "If the path you specify matches a file that Copilot is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used."
+
+### 4.3 Prompt Files
+
+Source: [code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files) (official)
+
+**Pattern:** `.github/prompts/<NAME>.prompt.md` — **manually invoked** task templates, fundamentally different from instructions:
+
+> "Unlike custom instructions that apply automatically, you invoke prompt files manually in chat."
+
+Instructions = rules/standards (always-on or pattern-matched). Prompt files = tasks/workflows (manually invoked via `/name`).
+
+**Frontmatter fields:** `name`, `description`, `argument-hint`, `agent`, `model`, `tools`.
+Body supports file references (`[name](path)` or `#file:path`), tool references (`#tool:name`), and variable syntax (`${workspaceFolder}`, `${selection}`, `${input:varName}`).
+
+### 4.4 Custom Agent Files
+
+**Pattern:** `*.agent.md` — custom agents with rich frontmatter.
+
+| Field         | Required | Description                                                    |
+| ------------- | -------- | -------------------------------------------------------------- |
+| `description` | **Yes**  | Agent purpose and capabilities                                 |
+| `name`        | No       | Display name                                                   |
+| `target`      | No       | `vscode` or `github-copilot` (defaults to both)                |
+| `tools`       | No       | List of tool names; defaults to all                            |
+| `infer`       | No       | Auto-selection based on task context (default: `true`)         |
+| `mcp-servers` | No       | Additional MCP servers (org/enterprise only for direct config) |
+| `metadata`    | No       | Key-value annotation                                           |
+
+Body max: **30,000 characters.**
+
+### 4.5 AGENTS.md Support
+
+Copilot reads AGENTS.md natively. The full list of supported instruction file types:
+
+- `/.github/copilot-instructions.md`
+- `/.github/instructions/**/*.instructions.md`
+- `**/AGENTS.md`
+- `/CLAUDE.md`
+- `/GEMINI.md`
+
+VS Code settings: `chat.useAgentsMdFile` (root), `chat.useNestedAgentsMdFiles` (subfolders, experimental).
+
+The coding agent reads `**/AGENTS.md` anywhere in the repo — **nearest file takes precedence** based on proximity to files being edited.
+
+### 4.6 Precedence
+
+> "Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot."
+
+1. **Personal** (highest) — via github.com/copilot interface
+2. **Repository** — copilot-instructions.md + matching scoped files + AGENTS.md
+3. **Organization** (lowest) — via org settings; GitHub.com only (not IDEs), public preview
+
+### 4.7 Coding Agent Environment
+
+**File:** `.github/workflows/copilot-setup-steps.yml` — GitHub Actions workflow for pre-installing dependencies.
+
+> "The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot."
+
+Must be on the default branch. Timeout capped at 59 minutes. The coding agent has read-only repo access and can only push to `copilot/` branches.
+
+### 4.8 Feature Support Matrix
+
+| Feature              | copilot-instructions.md | \*.instructions.md | AGENTS.md | Organization |
+| -------------------- | ----------------------- | ------------------ | --------- | ------------ |
+| Chat (GitHub.com)    | Yes                     | Yes                | —         | Yes          |
+| Chat (VS Code)       | Yes                     | Yes                | Yes       | No           |
+| Code review          | Yes                     | Yes (configurable) | —         | Yes          |
+| Coding agent         | Yes                     | Yes                | Yes       | Yes          |
+| **Code completions** | **No**                  | **No**             | **No**    | **No**       |
+
+> Custom instructions "are not taken into account for inline suggestions as you type in the editor."
+
+### 4.9 VS Code Settings
+
+| Setting                            | Purpose                                |
+| ---------------------------------- | -------------------------------------- |
+| `chat.instructionsFilesLocations`  | Where to find instruction files        |
+| `chat.promptFilesLocations`        | Where to find prompt files             |
+| `chat.includeApplyingInstructions` | Enable pattern-based matching          |
+| `chat.useAgentsMdFile`             | Enable AGENTS.md detection             |
+| `chat.useNestedAgentsMdFiles`      | Enable nested AGENTS.md (experimental) |
+| `chat.useClaudeMdFile`             | Enable CLAUDE.md detection             |
+
+---
+
+## 5. Cross-Provider Comparison
+
+### 5.1 File Pattern Scoping
+
+All three providers support file-pattern-based activation — this is the unifying "rules" concept:
+
+| Provider    | Mechanism                                | Frontmatter field           | Pattern syntax                       |
+| ----------- | ---------------------------------------- | --------------------------- | ------------------------------------ |
+| Claude Code | `.claude/rules/*.md`                     | `paths` (array)             | Glob: `**/*.ts`, `{src,lib}/**/*.ts` |
+| Cursor      | `.cursor/rules/*.mdc`                    | `globs` (string or array)   | Glob: `*.tsx`, `src/**/*.ts`         |
+| Copilot     | `.github/instructions/*.instructions.md` | `applyTo` (comma-separated) | Glob: `**/*.ts,**/*.tsx`             |
+
+### 5.2 Activation Modes
+
+| Mode                | Claude Code                            | Cursor                            | Copilot                                                |
+| ------------------- | -------------------------------------- | --------------------------------- | ------------------------------------------------------ |
+| Always on           | Rules without `paths` / CLAUDE.md      | `alwaysApply: true`               | copilot-instructions.md                                |
+| File-pattern scoped | Rules with `paths`                     | `globs` set                       | `applyTo` globs                                        |
+| Agent-determined    | Skills (via description)               | Agent Requested (via description) | N/A (description enables semantic matching in VS Code) |
+| Manual invocation   | Skills with `disable-model-invocation` | Manual @-mention                  | Prompt files (`/name`)                                 |
+
+### 5.3 Precedence Comparison
+
+| Provider    | Precedence (highest → lowest)                                                        |
+| ----------- | ------------------------------------------------------------------------------------ |
+| Claude Code | Managed > Project rules ≈ Project memory > User memory > Project local > Auto memory |
+| Cursor      | Team > Project > User                                                                |
+| Copilot     | Personal > Repository > Organization                                                 |
+
+### 5.4 AGENTS.md Support
+
+| Provider    | Native support                   | Nested                 | Import mechanism     |
+| ----------- | -------------------------------- | ---------------------- | -------------------- |
+| Claude Code | **No** (use `@AGENTS.md` import) | N/A                    | `@path` in CLAUDE.md |
+| Cursor      | **Yes** (first-class)            | Yes (hierarchical)     | N/A — read directly  |
+| Copilot     | **Yes** (`**/AGENTS.md`)         | Yes (nearest wins)     | N/A — read directly  |
+| Codex       | **Yes** (primary format)         | Yes (override pattern) | N/A — native         |
+
+---
+
+## 6. Quantitative Data: Sizes, Limits, Token Budgets
+
+### Hard Limits (Documented)
+
+| Provider       | Limit                                                             | Source                       |
+| -------------- | ----------------------------------------------------------------- | ---------------------------- |
+| Codex          | 32 KiB combined instruction files                                 | OpenAI Codex docs (official) |
+| Copilot        | ~1,000 lines max per file                                         | GitHub docs (official)       |
+| Copilot agents | 30,000 chars per agent body                                       | GitHub docs (official)       |
+| Claude Code    | Skill descriptions: 2% of context window (~16,000 chars fallback) | Claude Code docs (official)  |
+| Cursor         | No documented hard limit; 500 lines recommended                   | Cursor docs (official)       |
+
+### Practical Sizing
+
+| Metric                      | Target                                              | Source type                                                                                 |
+| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Root instruction file       | 60–500 lines (300 good target)                      | Practitioner consensus                                                                      |
+| Scoped rules / .mdc files   | Under 50–80 lines each                              | Community consensus                                                                         |
+| SKILL.md / prompt files     | Under 500 lines; move reference to supporting files | Official (Claude)                                                                           |
+| Total instruction budget    | Under 32 KiB as safe cross-provider ceiling         | Official (Codex)                                                                            |
+| Fresh monorepo session cost | ~20k tokens (10% of 200k budget)                    | Practitioner ([Shrivu Shankar](https://blog.sshh.io/p/how-i-use-every-claude-code-feature)) |
+| LLM instruction adherence   | Degrades significantly above 150–200 instructions   | [Builder.io](https://www.builder.io/c/docs/ai-instruction-best-practices) (non-official)    |
+
+---
+
+## 7. Context Engineering Principles
+
+Source: [Anthropic Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (official)
+
+1. **Context is a finite resource with diminishing returns.** Attention budget constraints mean more context does not equal better results.
+
+2. **Pursue the minimal set** of information that fully outlines expected behavior. Start minimal, add based on observed failures.
+
+3. **Use progressive disclosure.** Always-on rules should be minimal; domain knowledge should load on demand via skills or scoped rules.
+
+4. **Few-shot examples over exhaustive edge case lists.** "Examples are the pictures worth a thousand words."
+
+5. **Structural format.** Organize instructions into distinct sections using Markdown headers. Put critical rules near the top (positional recall bias).
+
+Source: [Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html) (reputable engineering source)
+
+Context loading strategies:
+
+- **LLM-controlled**: Agent decides when context is needed (skills, agent-requested rules)
+- **Human-triggered**: Explicit activation via commands (manual rules, prompt files)
+- **Deterministic**: Tool-driven events (hooks, auto-attached rules)
+
+---
+
+## 8. Best Practices (Cross-Provider Consensus)
+
+These practices converge across official docs from Anthropic, GitHub, and Cursor, plus reputable engineering sources.
+
+### What to Include
+
+- Build, test, lint commands the agent cannot guess
+- Code style rules that differ from language defaults
+- Repository etiquette (branch naming, PR conventions)
+- Architectural decisions specific to the project
+- Developer environment quirks (required env vars)
+- Common gotchas or non-obvious behaviors
+- The "WHY" behind conventions (improves edge case handling)
+- Three-tier boundaries: Always / Ask First / Never
+
+### What to Exclude
+
+- Anything the agent can figure out by reading code
+- Standard language conventions the agent already knows
+- Detailed API documentation (link instead)
+- Code style that a linter enforces — "never send an LLM to do a linter's job" ([Builder.io](https://www.builder.io/blog/agents-md), non-official)
+- Information that changes frequently
+- Long explanations or tutorials
+- One-off task-specific instructions (pollute long-term context)
+
+### Writing Style
+
+- Use concrete, specific language; avoid vague instructions
+- Provide real-world examples from the actual codebase
+- Use markdown headings for clear section organization
+- Keep instructions short and self-contained
+- Use emphasis ("IMPORTANT", "YOU MUST") sparingly for critical rules (Claude official)
+- Provide alternatives ("use Y instead") rather than only prohibitions ("never use X")
+
+### Iterative Development
+
+- Start small; add rules based on what the agent gets wrong, not as comprehensive manuals
+- "Each addition should solve a real problem you have encountered, not theoretical concerns" ([Addy Osmani](https://addyosmani.com/blog/good-spec/), non-official)
+- Treat instruction files like code: review when things go wrong, prune regularly, version control
+- "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long" (Claude official)
+
+---
+
+## 9. Anti-Patterns
+
+### Content Anti-Patterns
+
+1. **Over-specified instruction files**: Too long; agent ignores critical rules lost in noise. Fix: ruthlessly prune.
+2. **Vague instructions**: "Most agent files fail because they're too vague." ([Addy Osmani](https://addyosmani.com/blog/good-spec/), non-official) Fix: be specific with examples.
+3. **Auto-generated instruction files**: These are high-leverage documents requiring careful manual curation.
+4. **Stale rules**: Rules that don't match current framework/API versions cause deprecated code generation.
+5. **Kitchen sink sessions**: Mixing unrelated tasks pollutes context. Fix: clear between tasks. (Claude official)
+6. **Dumping entire documentation**: Without summarization, this overwhelms the agent. Fix: link to docs instead.
+
+### Structural Anti-Patterns
+
+7. **Copy/pasting root content into scoped files**: Creates drift. Fix: use imports or references.
+8. **Circular imports or deep include chains**: Fix: max 5 hops (Claude), keep flat.
+9. **Relying on subtle tool-specific precedence**: Different tools merge differently. Fix: design so intent is clear regardless of tool.
+10. **Over-scoping monorepos into dozens of tiny files**: Fix: scope only where real divergence exists.
+
+---
+
+## 10. Portability Strategy
+
+### The Fragmentation Problem
+
+Each tool has its own format: Claude (`CLAUDE.md` + `.claude/`), Cursor (`.cursor/rules/*.mdc`), Copilot (`.github/copilot-instructions.md` + `.github/instructions/`), Codex (`AGENTS.md`), Junie (`.junie/guidelines.md`). This creates maintenance burden and content drift.
+
+### AGENTS.md as Convergence Point
+
+AGENTS.md (stewarded by the Linux Foundation's Agentic AI Foundation) has 60,000+ repos and 20+ compatible tools. It serves as the lowest-common-denominator standard — the "EditorConfig for coding agents." It cannot express tool-specific features (glob scoping, skill metadata, hooks) but works for shared content.
+
+### Recommended Layered Approach
+
+1. **Canonical content** in AGENTS.md or a shared source directory
+2. **Tool-specific adapters** that import/sync from the canonical source
+3. **Tool-specific extensions** for features that don't port (Claude rules with `paths`, Cursor `globs`, Copilot `applyTo`)
+
+The three-tier discovery pattern (global > project root > nested/scoped) is consistent across all providers and provides a natural adapter surface.
+
+---
+
+## 11. Sources
+
+### Official Documentation (Highest Reliability)
+
+- [Claude Code Memory Docs](https://code.claude.com/docs/en/memory) — CLAUDE.md hierarchy, @-imports, rules, auto memory
+- [Claude Code Settings](https://code.claude.com/docs/en/settings) — Settings hierarchy, permissions
+- [Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) — What to include/exclude, anti-patterns
+- [Claude Code Skills](https://code.claude.com/docs/en/skills) — Skills vs rules vs CLAUDE.md
+- [Cursor Rules Docs](https://cursor.com/docs/context/rules) — .mdc format, frontmatter, activation modes, AGENTS.md, precedence
+- [GitHub Copilot Custom Instructions](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) — File format, scoped instructions, precedence
+- [VS Code Copilot Customization](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) — VS Code settings, AGENTS.md, CLAUDE.md support
+- [VS Code Prompt Files](https://code.visualstudio.com/docs/copilot/customization/prompt-files) — Prompt file format and frontmatter
+- [GitHub Copilot Custom Agents Reference](https://docs.github.com/en/copilot/reference/custom-agents-configuration) — Agent file format
+- [GitHub Copilot Coding Agent Environment](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment) — copilot-setup-steps.yml
+- [GitHub Copilot Organization Instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions) — Org-level settings
+- [Anthropic Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Foundational principles
+- [AGENTS.md Specification](https://agents.md/) — Cross-tool standard, governance
+- [OpenAI Codex AGENTS.md Guide](https://developers.openai.com/codex/guides/agents-md/) — 32KiB limit, hierarchy, override pattern
+- [Feature Request: AGENTS.md in Claude Code — Issue #6235](https://github.com/anthropics/claude-code/issues/6235) — Current status
+
+### Reputable Engineering Blogs (High Reliability)
+
+- [Martin Fowler — Context Engineering for Coding Agents](https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html) — Context loading strategies taxonomy
+- [Addy Osmani — How to Write a Good Spec for AI Agents](https://addyosmani.com/blog/good-spec/) — Spec structure, boundary tiers
+- [Builder.io — Skills vs Rules vs Commands](https://www.builder.io/blog/agent-skills-rules-commands) — Taxonomy, progressive disclosure
+- [Builder.io — AGENTS.md Guide](https://www.builder.io/blog/agents-md) — Practical tips, safety permissions
+- [Trigger.dev — How to Write Great Cursor Rules](https://trigger.dev/blog/cursor-rules) — .mdc best practices
+- [.NET Blog — Prompt Files and Instructions Files Explained](https://devblogs.microsoft.com/dotnet/prompt-files-and-instructions-files-explained/) — Copilot prompt files vs instructions
+
+### Practitioner Reports (Medium-High Reliability)
+
+- [Shrivu Shankar — How I Use Every Claude Code Feature](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) — 13KB CLAUDE.md in practice, 20k token startup cost
+- [HumanLayer — Writing a Good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) — 300-line target, 100 instruction max
+- [Arun Iyer — Instruction Files for AI Coding Assistants](https://aruniyer.github.io/blog/agents-md-instruction-files.html) — Cross-tool comparison
+
+### Research
+
+- [ManyIFEval — "Curse of Instructions"](https://openreview.net/forum?id=R6q67CDBCH) — Instruction count vs compliance
+- ["Lost in the Middle"](https://arxiv.org/abs/2307.03172) — Positional recall bias
+- [Context Degradation — Chroma Research](https://research.trychroma.com/context-rot) — Long-context precision loss