AI Rulebook: Always-On Rules for AI Coding Agents

What it is

AI Rulebook is a free, MIT-licensed extension for VS Code and VS Code-compatible editors, published by my company, Wyvern Systems LLC. It installs a small set of always-on engineering rules for AI coding agents into a project's AGENTS.md, and gives you a sidebar to turn each rule on and off.

I built it because I kept pasting the same guidance into every AI chat: stay in scope, reuse what exists, run the tests, keep the docs honest, don't touch git unless asked. Agents follow instructions best when they are written down in the repo, so the extension writes them down once and keeps them there.

One file, many agents

AGENTS.md is the shared instruction file that a growing list of tools reads: Cursor, Cline, opencode, Windsurf, and supported GitHub Copilot features. Claude Code reads CLAUDE.md, so the extension adds a one-line @AGENTS.md import there. Commit both files and every teammate and every terminal agent gets the same rules without installing anything.

This site is a working example: its own AGENTS.md carries the rule pack.

The six rules

• Scope: inspect the relevant code first, make the smallest complete change, verify it, and report unrelated issues instead of fixing them.
• Code: reuse existing helpers and module boundaries, vet new dependencies, validate input at trust boundaries, and never log or commit secrets.
• Tests: test observable behavior, reproduce bugs with a regression test, run the project's real test command, and report results accurately. The extension detects that command from package.json, Cargo.toml, go.mod, pytest config, or a Makefile.
• Docs: update documentation the change made inaccurate and add user-facing release notes.
• Markdown: one H1, no skipped headings, - bullets, and language tags on code fences.
• Git: preserve existing work, no commits or pushes unless asked, and never rewrite pushed history.

How it edits AGENTS.md

Everything the extension owns lives between <!-- ai-rulebook:start --> and <!-- ai-rulebook:end --> markers, with one marked section per rule. Turning a rule off removes its text and marks the section disabled; turning it back on writes the text back from the bundle. Anything you wrote outside the block is left alone, and the extension refuses to touch a block whose markers have been damaged. A status bar item shows how many rules are on, for example AI 5/6.

Token-efficient subagent mode

Version 4.3.0 added an optional mode, off by default, for tools that can spawn subagents. It tells the agent to keep its expensive session model for judgment (planning, writing specs, the final report) and to hand searching, editing, and check runs to cheaper models. It names model tiers (fast, standard, and deep) rather than one vendor's models, says what to substitute when a model is unavailable, and spells out what each delegate must return, so it works in Claude Code, Codex, Cursor, opencode, and GitHub Copilot alike.

Get it

Search for AI Rulebook in the Extensions panel, or run ext install WyvernSystemsLLC.ai-rulebook from the command palette. It is on both the Visual Studio Marketplace and Open VSX, the registry used by VSCodium, Windsurf, and other forks. If you just want the rules without the extension, copy the standalone AGENTS.md from the source repository.

A caveat worth stating plainly: rules are instructions, not enforcement. An agent can still misread or drop them in a long session, so restate the rule that matters when that happens.