AI Rulebook
One set of engineering rules for every AI coding agent on your project, managed from a sidebar in VS Code.
ext install WyvernSystemsLLC.ai-rulebook- PriceFree
- LicenseMIT
- RequiresVS Code 1.85+
- WritesAGENTS.md, CLAUDE.md
Overview
AI coding agents are fast, but without guidance they drift: they touch code nobody asked them to change, skip the tests, and leave the docs out of date. AI Rulebook gives them a short, consistent set of engineering rules to follow in every session.
The rules live in your project's AGENTS.md, the shared instructions file read by Cursor, Cline, opencode, Windsurf, and supported GitHub Copilot features. Claude Code picks them up through a one-line @AGENTS.md import in CLAUDE.md. Commit both files and every teammate and every tool works from the same rules, with nothing extra to install.
A sidebar lets you turn each rule on or off. Every toggle edits that rule's section of AGENTS.md in place, and anything you wrote outside the managed block stays exactly as you left it.
<!-- ai-rulebook:start -->
<!-- ai-rulebook:rule scope enabled -->
## Scope
- Change only what the task requires. ...
<!-- ai-rulebook:end-rule scope -->
<!-- ai-rulebook:rule git disabled -->
<!-- ai-rulebook:end-rule git -->
<!-- ai-rulebook:end -->Features
One file for every agent
Rules are written to AGENTS.md, so Cursor, Cline, opencode, Windsurf, GitHub Copilot, and Claude Code all read the same instructions.
Toggle rules one by one
Sidebar checkboxes turn each rule on or off, and a status bar count such as AI 5/6 shows how many are active.
Respects your existing file
Only the block between its markers is managed. Your own text is preserved, and a block with damaged markers is never overwritten.
Knows your test command
The Tests rule names your real command, detected from npm, pnpm, yarn, bun, Cargo, Go, pytest, or a Makefile.
Installs itself where it's needed
Projects that already use an AI agent get the rule pack automatically on open. Turn that off with a single setting.
Optional subagent mode
Off by default. Tells agents to keep judgment on the main model and delegate searches, edits, and check runs to cheaper subagents.
The six rules
- Scope
- Finish and verify the task that was asked, keep changes in scope, and follow the project's conventions.
- Code
- Reuse existing helpers and module boundaries, vet dependencies, validate untrusted input, and keep error context.
- Tests
- Test observable behavior, add regression tests for bugs, run the project's checks, and report results accurately.
- Docs
- Update documentation the change made inaccurate and add user-facing release notes where they belong.
- Markdown
- One H1, no skipped heading levels, language-tagged code fences, and relative links.
- Git
- Preserve existing work, never commit or push unless asked, and never rewrite pushed history.
Get started
Install the extension
Search for AI Rulebook in the Extensions panel, or install it from the VS Marketplace or Open VSX.
Open your project
If the project already uses an AI agent, the rule pack installs automatically. Otherwise run “AI Rulebook: Install / update rule pack” from the Command Palette.
Choose your rules
Use the AI Rulebook sidebar to switch individual rules on or off.
Commit AGENTS.md and CLAUDE.md
Teammates and terminal tools such as Claude Code and opencode then get the same rules without installing anything.
Works with
Runs in
- VS Code
- Cursor
- Windsurf
- VSCodium
- code-server
- Eclipse Theia
Rules are read by
- Cursor
- Claude Code
- GitHub Copilot
- Cline
- opencode
- Windsurf
Questions
Do I need the extension to use the rules?
No. Each GitHub release includes a standalone AGENTS.md. Copy it into your project root and replace the placeholder test command with your own.
Will it overwrite my existing AGENTS.md?
No. It adds or updates one block between its own markers and leaves everything else in the file alone. If those markers are damaged, it stops rather than guess.
Does it work with Claude Code?
Yes. Claude Code reads CLAUDE.md, so the extension adds a single @AGENTS.md import line there. Your existing CLAUDE.md instructions are kept.
Do the rules guarantee an agent follows them?
No. Rules are instructions, not enforcement. Agents can still miss them, especially late in long sessions, so restate the rule that matters when that happens.
Can I stop it from installing automatically?
Yes. Set aiRules.autoInstallOnOpenWorkspace to false in your settings.