The Agent Engineering Kit

Rules

The rules your agent reads every session.

The kit adds one marked block to AGENTS.md, which almost every AI coding tool reads. It holds the core rules as short pass/fail lines, about 600 tokens, so it costs little in every session. Everything longer lives in a rulebook that skills and agents open one section at a time.

§01 · The always-on block

Word for word, as it’s installed.

It sits between <!-- agent-engineering-kit:start --> and <!-- agent-engineering-kit:end -->, so an update replaces it in place and uninstall removes it cleanly. Your own sections of AGENTS.md stay yours, and the block says they take priority.

AGENTS.mdEngineering rules (Agent Engineering Kit)

These rules apply to every task; this file's other instructions and the project's own conventions take priority. For detail, open only the section you need in .agent-kit/RULES.md: §1 stack, §2 workflow, §3 principles, §4 code quality, §5 testing, §6 security, §7 UI, §8 review checklist, §9 debugging, §10 git.

Before coding

  • If the request is ambiguous, ask one focused question. Never guess silently; state each assumption you make.
  • For anything beyond a trivial fix, get a plan approved before editing code.
  • Read the code you'll change, and 2–3 existing files of the same kind; match their style and patterns.
  • Use only APIs you have confirmed exist in the installed versions.
  • Write down what "done" means as checks that pass or fail: a test, a command and its output, an observable result.

While coding

  • Every changed line traces to the request. Unrelated problems go in the report, not the diff.
  • Add no features, options, abstractions or dependencies that weren't asked for.
  • Never delete, skip or weaken a test, suppress a lint or type error, or swallow an error to make a check pass.
  • Put no secrets, credentials or environment-specific values in code.
  • Use the domain terms in GLOSSARY.md (or CONTEXT.md), if present.

Done means all of these are true

  • The project's format, lint, type-check, test and build commands pass (those that exist).
  • The changed behavior was exercised for real, not only compiled.
  • New or changed logic has a test, or the report says why not.
  • The diff passes the review checklist (§8): no dead code, debug output, commented-out code or narrating comments.
  • The report lists what changed, the commands run and their results, and anything not verified. Without that evidence, it isn't done.

Workflows

  • Features or multi-file changes: the feature skill. Small, contained fixes: the quick-fix skill. Before saying done: the verify-change skill. To commit: the ship skill. For anything non-trivial, align with me before coding.
  • When a skill says "use the X agent": delegate to your tool's X sub-agent if it has one; otherwise read .agent-kit/agents/X.md and do that work yourself, in a separate pass.
  • When I correct a mistake, propose a lasting fix with the learn skill.

§02 · The rulebook

Reference, not context.

.agent-kit/RULES.md is the detail behind the block. It isn’t loaded into every session: a skill or agent cites the section it needs (§2 for the workflow, §8 for the review checklist, §9 for debugging) and opens only that one. Read the whole rulebook on GitHub.

  1. §1 Adapting to Any Tech Stack
  2. §2 Workflow
  3. §3 Core Principles
  4. §4 Code Quality
  5. §5 Testing
  6. §6 Security
  7. §7 Frontend / UI (when the project has a UI)
  8. §8 Review Checklist (run before presenting any change)
  9. §9 Debugging
  10. §10 Git, Commits & Pull Requests

§03 · How each tool reads it

One file, read everywhere.

  1. Most tools read AGENTS.md on their own: Codex, Cursor, GitHub Copilot, Antigravity, Windsurf, Kiro, opencode, Zed, Amp, Warp and others.
  2. Claude Code gets a marked one-line @AGENTS.md import in CLAUDE.md, below anything you already have there.
  3. Gemini CLI gets AGENTS.md added to context.fileName in .gemini/settings.json, keeping GEMINI.md.
  4. Aider doesn’t read AGENTS.md by itself; the installer tells you the one line to add to .aider.conf.yml.

What every tool gets, and why.

§04 · Make it yours

Your project’s rules come first.

  1. Workflow Preferences. Add this section to the project part of AGENTS.md: where plans go, the test policy, commit style, when to ask first. The skills read it before their own defaults, and updates never touch it.
  2. Lessons stick. When you correct the agent, /learn writes the lesson as one specific rule and proposes where it goes. It applies the rule only after you approve.
  3. Keep it short. A test in the kit fails if the always-on block grows past 4,000 characters, roughly 1,000 tokens.