Compound Engineering for Claude Code + AGENTS.md

Last updated: April 29, 2026

TL;DR

The Compound Engineering plugin ships 36 skills and 51 agents that turn Claude Code into a structured dev pipeline – brainstorm, plan, work, test, review, document. But the plugin only delivers on its promise ("each unit of work makes the next one easier") if your process is documented somewhere Claude reads first. That somewhere is AGENTS.md – a sibling file to CLAUDE.md that loads before the rest of your context. This post walks through the actual AGENTS.md from a production app I'm building (SoccerSkills.app), the 12-step pipeline it encodes, and why splitting process out of CLAUDE.md made my workflow noticeably tighter inside a week.

The CLAUDE.md problem

Every Claude Code project starts the same way. You create a CLAUDE.md at the repo root. It has code style, dependencies, framework quirks, and – at the bottom, where it gets ignored – a few lines about how you actually want work to flow. Use Linear for issues. Branch naming convention. Where tests live.

Two months later, the file is 800 lines. The dev process is buried under code conventions. New tasks don't pick up the right pipeline because Claude has read 600 lines of "how to format imports" before it gets to "always create a Linear issue first."

That's the problem. Process and codebase context are different jobs. Stuffing them into one file means neither one reads cleanly.

The fix is structural: split them. CLAUDE.md keeps the codebase context. AGENTS.md carries the development process. Claude Code reads AGENTS.md first, so process anchors everything that follows.

What is AGENTS.md

AGENTS.md is a Markdown file at the root of a repository that documents how AI coding agents should work in that codebase. Claude Code reads it before CLAUDE.md. It's the right home for development-process content – issue tracking, branch naming, commit conventions, PR rules, the /ce-* skills you want fired in what order, and tier rules for routine vs standard vs safety-critical changes. Code-formatting rules, framework guardrails, and dependency notes still belong in CLAUDE.md.

The split matters because Claude Code reads context top-to-bottom. Whatever loads first sets the frame for the rest. If your dev process is at the bottom of an 800-line file, it's competing with code style notes for attention. If it's in its own file at position one, it shapes every prompt from the first turn.

What is Compound Engineering

Compound Engineering is an open-source Claude Code plugin from Every Inc. that ships 36 skills and 51 agents structured around a single belief: each unit of engineering work should make the next unit easier. The plugin is MIT licensed, has 123+ releases, and works on Claude Code, Codex, Cursor, Copilot, and Gemini CLI.

The plugin's core philosophy is "80% of engineering is in planning and review, 20% is in execution." The skills enforce that ratio by making planning and review first-class commands instead of optional steps you skip when you're tired.

Install with one command:

/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering

Once installed, you have a structured toolkit: brainstorm an idea, plan the implementation, do the work, run tests, review the code, draft the PR, and – critically – document what you learned for future sessions to find.

The 7 commands you'll actually use

There are 29 more skills (debug, test-browser, worktree, pr-description, resolve-pr-feedback, clean-gone-branches, frontend-design, and many specialized reviewers). The seven above are the spine of the daily loop.

My AGENTS.md, walked through

Here's the actual structure I'm running on SoccerSkills.app, the consumer SaaS I'm building live across the Production Claude Code series.

The pipeline

The whole development process compiles down to 12 steps:

[Linear: WOT-N created]
  → /ce-brainstorm → /ce-plan
  → /ce-worktree (branch: <type>/WOT-N-<slug>) → manually move to In Progress
  → /ce-work (commits reference WOT-N)
  → /ce-test-browser
  → /ce-code-review
  → /ce-pr-description (PR body includes "Closes WOT-N")
  → /ce-commit-push-pr → manually move to In Review
  → /ce-resolve-pr-feedback
  → [merge PR] → manually move to Done
  → /ce-compound (writes to docs/solutions/)

Not every step fires every time. The tier rules below decide what runs.

Tier rules (blast-radius based)

The biggest practical win from documenting the process: not every change deserves the full pipeline. Some are routine. Some can blow up production. The pipeline has to scale to the risk.

Safety-critical work runs at effort: max (set in CLAUDE.md). /ce-code-review is mandatory before merge for that tier.

The tier list isn't theoretical. It names actual paths in my repo. That specificity is what makes the rules executable instead of advisory – Claude can see whether a file matches the safety-critical pattern and fire the right pipeline automatically.

Linear issue tracking

Every PR maps to at least one Linear issue (WOT-N). For multi-PR work, there's a parent issue and one sub-issue per PR. The parent stays open until all subs close.

Status moves are manual – I don't trust auto-status from GitHub. The pipeline tells Claude when to move issues:

Closes WOT-N in commit/PR bodies is required as an audit reference. It does not auto-close the issue – status moves stay manual.

Branching, commits, and PRs

AGENTS.md encodes the conventions so Claude doesn't have to guess:

• Branch: <type>/WOT-N-<short-slug> (e.g., feat/WOT-12-classifier-foundation)
• Commits: <type>(scope): subject with Refs WOT-N body
• PR title: <type>(WOT-N): <descriptive subject>
• PR body: must include Closes WOT-N, plan reference, test plan, and any out-of-scope callouts

/ce-commit-push-pr follows this convention without any extra prompting. That's the leverage of putting it in AGENTS.md – I prompted Claude once, it codified the rule, and now every commit and PR follows the convention by default.

Why split AGENTS.md from CLAUDE.md

Three reasons.

One: read order matters. Claude Code reads AGENTS.md before CLAUDE.md. Process loaded first means process shapes the rest. If you bury workflow rules in line 600 of CLAUDE.md, they're competing for attention with import-style notes.

Two: scope separation. CLAUDE.md is about the codebase. AGENTS.md is about how you work in any codebase. The two have different change cadences. Codebase context shifts with every refactor. Process changes maybe once a quarter. Mixing them means every code-style update muddies the process file's git history.

Three: composability. AGENTS.md is portable across projects. The tier rules, the Linear conventions, the commit format – those work in every Next.js + Drizzle + Stripe project I build. I can copy AGENTS.md to a new repo, swap the Linear team prefix, and the process is live on day one. CLAUDE.md is project-specific. AGENTS.md is process-specific. Different lifetimes, different files.

The /ce-compound skill: the part most people miss

/ce-compound is the command that makes "compound engineering" actually compound. After any non-trivial fix, decision, or pattern discovery, it writes a structured Markdown file to docs/solutions/ capturing:

• The problem you solved
• The approach that worked
• What you tried that didn't
• Tags and module references for future search

Six months from now, when a new task touches the same area, the relevant docs/solutions/ file shows up in /ce-learnings-researcher's scan. The next session inherits the work from the last one. That's the loop the plugin's name promises – work that compounds instead of decays.

The discipline matters. Skip /ce-compound and the plugin reduces to a glorified todo runner. Run it after every non-trivial change and your docs/solutions/ becomes the institutional memory of the codebase.

5 steps to install and set up

1. Install the plugin.

   /plugin marketplace add EveryInc/compound-engineering-plugin
   /plugin install compound-engineering
   

2. Create AGENTS.md at the repo root. Start with the pipeline, tier rules, and your issue-tracker conventions. Use my SoccerSkills.app AGENTS.md as a template if it helps – fork the structure, swap the Linear prefix and tier specifics for your repo.

3. Move your existing dev-process content out of CLAUDE.md into AGENTS.md. Keep code style, dependencies, framework guardrails in CLAUDE.md. Move Linear conventions, branch naming, commit format, tier rules, the pipeline itself.

4. Add a docs/solutions/ directory for /ce-compound to write into. Create category subdirectories as you accumulate them (performance-issues/, architecture-patterns/, conventions/).

5. Run a Routine-tier change end-to-end to verify the pipeline fires correctly. A small UI tweak with a Linear issue, branch, commit, PR, merge. If /ce-commit-push-pr follows your conventions without prompting, the file is doing its job.

After that, the next non-trivial change is the real test. Run /ce-brainstorm, watch the requirements doc come back. Run /ce-plan, watch the task list materialize. Run /ce-work, then /ce-code-review, then /ce-commit-push-pr. End with /ce-compound. That's the full loop, and once you've done it once, you don't go back.

What this complements vs replaces

Versus the superpowers plugin (Anthropic's official): Compound Engineering complements rather than replaces. Superpowers covers brainstorming, planning, code-review, and code-simplification at a more general level. Compound Engineering goes deeper on the work-execution loop and the compound-knowledge piece. You can run both. Some teams will pick one. The choice is workflow preference, not capability.

Versus raw CLAUDE.md only: This is the upgrade most people should make. AGENTS.md + Compound Engineering takes the same prompts you were already typing into Claude Code and codifies them once, in a file Claude reads first, so you stop typing them.

Versus a Linear-only workflow with no plugin: If you're already disciplined about Linear issues + branches + PR conventions, you've done the hardest part. The plugin adds the planning, review, and compound-knowledge layers that turn "I follow a process" into "the process runs itself."

What I'd change after a week of using it

Two notes from production use:

One: I removed /ce-worktree from my pipeline. I prefer linear branching to parallel worktrees. The plugin supports both; pick the one that matches how you actually work and document the choice in AGENTS.md.

Two: my AGENTS.md still has a Next.js 16 guardrail block at the top (the framework changed enough that Claude's training data is wrong about routes and APIs). That's a hint that AGENTS.md is the right home for any "read this before you do anything" rule, not just the development process. Framework migration notes, project-specific gotchas, anything that has to anchor every prompt.

The dev process is the lead. Other always-read rules can ride along.

What's next

If you're following the Production Claude Code series, this is the kind of structural change Episode 5 will go deep on (CLAUDE.md you actually want in a real codebase). The AGENTS.md pattern is the missing companion to that.

If you're tracking how AI coding tooling decisions like this play out across hundreds of real production systems, the WotAI community on Skool has 700+ builders sharing notes weekly. Free to join.

The video walkthrough of this exact setup is on YouTube: Compound Engineering for Claude Code + AGENTS.md.

FAQ

What is AGENTS.md in Claude Code?

AGENTS.md is a Markdown file at the root of a repository that documents how AI coding agents should work in that codebase. Claude Code reads it before CLAUDE.md. It's the right home for development-process content – issue tracking conventions, branch naming, commit format, tier rules, and the pipeline of /ce-* or other skills you want fired in what order. It loads first, so it anchors every prompt.

What is the Compound Engineering plugin?

Compound Engineering is an open-source Claude Code plugin from Every Inc. that ships 36 skills and 51 agents structured around a single belief: each unit of engineering work should make the next unit easier. It's MIT licensed, has 123+ releases, and works on Claude Code, Codex, Cursor, Copilot, and Gemini CLI. The core commands are /ce-ideate, /ce-brainstorm, /ce-plan, /ce-work, /ce-code-review, /ce-commit-push-pr, and /ce-compound.

How do I install Compound Engineering in Claude Code?

Run two commands in Claude Code: /plugin marketplace add EveryInc/compound-engineering-plugin to register the marketplace, then /plugin install compound-engineering to install. The plugin is MIT licensed and free. Once installed, the /ce-* commands are available in any Claude Code session.

Why split AGENTS.md from CLAUDE.md?

Three reasons. Read order matters – Claude reads AGENTS.md first, so process anchors the rest of the context. Scope separation – CLAUDE.md is about the codebase, AGENTS.md is about how you work, and they have different change cadences. Composability – AGENTS.md is portable across projects (the tier rules, Linear conventions, and commit format work in any repo with the same shape), while CLAUDE.md is project-specific.

What goes in AGENTS.md vs CLAUDE.md?

AGENTS.md holds development process: issue tracking conventions, branch naming, commit format, PR body structure, the pipeline of skills/commands to fire, tier rules for routine/standard/safety-critical changes, and any "read this before doing anything" guardrails (like a framework version warning). CLAUDE.md holds codebase context: code style, dependencies, framework conventions, file layout, and project-specific rules that don't transfer to other repos.

What does /ce-compound do?

/ce-compound is a Compound Engineering command that documents the learnings from a just-finished task into a docs/solutions/ directory. It captures the problem you solved, the approach that worked, what you tried that didn't, and tags the entry with module references and problem types for future search. Six months later, when a new task touches the same area, /ce-learnings-researcher finds the entry and the next session inherits the work. This is the mechanism that makes "compound engineering" actually compound instead of decay.

How is Compound Engineering different from the superpowers plugin?

Compound Engineering and the superpowers plugin (Anthropic's official) overlap in coverage – both ship brainstorming, planning, code-review, and code-simplification skills. Compound Engineering goes deeper on the execution loop (/ce-work's built-in test discovery and scenario checks) and on knowledge compounding (/ce-compound writing to docs/solutions/). They're complementary, not competing. Some teams will run both; the choice is workflow preference.

What are tier rules in AGENTS.md?

Tier rules categorize changes by blast radius (how much damage a bad change could cause) and assign each tier a different pipeline depth. Routine changes (UI tweaks, lint fixes, dep bumps) skip planning and run /ce-work directly. Standard changes (new components, routes fitting existing patterns) run /ce-plan → /ce-work → /ce-code-review → /ce-commit-push-pr. Safety-critical changes (auth, billing, anything that touches production data integrity) run the full pipeline at maximum effort with mandatory test-first execution. Tier rules let process scale to risk.

Do I need to use Linear for this to work?

No. The AGENTS.md template uses Linear because that's what I run, but the pipeline works with any issue tracker. Replace the WOT-N references with whatever ID format your tracker uses (Jira's PROJ-123, GitHub Issues' #123, Notion's database IDs). The point is one issue per unit of work, branch and commit references that link back to the issue, and manual status transitions at clear lifecycle points.

How do I write my own AGENTS.md from scratch?

Start with the pipeline. List the steps a unit of work goes through in your repo today, end-to-end. Then add tier rules categorizing changes by risk. Then add issue-tracker, branch, commit, and PR conventions. Then add any framework guardrails or "read first" rules that anchor every prompt. The whole file should fit in a single screen-scroll – if it's longer, split it. Use my SoccerSkills.app AGENTS.md as a starting template and modify the specifics for your repo.

What's the difference between /ce-work and /ce-plan?

/ce-plan produces a structured implementation plan from a requirements document – task-by-task breakdown, file changes, test scenarios, dependencies. /ce-work executes a plan, running through tasks one at a time with built-in test discovery, scenario completeness checks, and progress tracking. Plan first, then work. Skipping the plan on standard or safety-critical work is the most common mistake new users make – the plugin's value comes from enforcing the planning step, not skipping it.