Skip to main content
New aislop v0.13.1 patch — calibrates hidden-fallback detection and fixes regex comment-masker false positives. Read the changelog →
← Blog
Reference · 5 min read

AI Coding Standards: A Copyable Rules File for Claude, Cursor, Codex, and Copilot

A good rules file tells an agent how this repository works. A good engineering system also checks whether the agent followed it.

Most AI coding rules files fail in one of two ways. They are vague—“write clean, secure, maintainable code”—or they are enormous style manuals the agent cannot prioritize.

A useful file is closer to onboarding for a capable new engineer. It explains where work belongs, how the repository proves correctness, which constraints are non-negotiable, and what evidence must exist before the task is complete.

Instructions guide behavior. Executable gates verify behavior. You need both.

Choose one source of truth

AGENTS.md is an open Markdown format designed as a README for coding agents. Tool support differs. Claude Code loads CLAUDE.md; Cursor supports scoped files in .cursor/rules and can also read root agent files in its CLI; GitHub Copilot supports repository-wide and path-specific instruction files as well as AGENTS.md context.

Do not maintain four conflicting standards by hand. Keep the stable repository contract in one source, then use small tool-specific files only for capabilities or syntax unique to that tool. Verify loading behavior in the official docs because these products evolve quickly.

The copyable core

# Repository instructions ## Mission - State what this system does and the users it protects. - Optimize for the requested outcome, not for maximum code generation. ## Before editing - Read the nearest instructions and the files that own the behavior. - Inspect existing patterns and recent similar changes. - Restate the acceptance criteria and identify the highest-risk boundary. - Do not edit until the task and verification path are clear. ## Scope - Make the smallest change that satisfies the acceptance criteria. - Do not reformat, rename, or refactor unrelated code. - Do not add dependencies, configuration, or abstractions for hypothetical future use. - Preserve user work and existing public behavior unless the task explicitly changes it. ## Architecture - Keep untrusted input at system boundaries and parse it into domain types. - Put business rules in the existing domain owner; do not create a parallel layer. - Reuse established repository patterns before inventing a new one. - Make invalid states difficult or impossible to represent. ## Errors and security - Never swallow errors or turn every failure into a successful empty result. - Preserve error causes and add context once at the boundary that can act on them. - Enforce authorization server-side at the resource boundary. - Never expose secrets, personal data, internal paths, or raw stack traces. - Independently verify every new dependency, API, and configuration key. ## Tests and evidence - Add or update a test that fails without the change. - Cover the relevant failure, empty, timeout, duplicate, and permission paths. - Run the exact build, type, lint, test, security, and quality commands below. - For UI changes, verify the real rendered flow at required viewport sizes. - Report what was verified and what remains unverified. ## Code quality - Prefer direct, readable code over one-call wrappers and speculative abstractions. - Use domain names; avoid generic names such as data, item, result, and handler. - Comments explain non-obvious constraints and tradeoffs, not visible syntax. - Remove dead code, debug output, placeholders, unsafe type escapes, and abandoned edits. - Keep functions and files within the repository's documented limits. ## Required commands - Install: REPLACE_WITH_PROJECT_COMMAND - Build: REPLACE_WITH_PROJECT_COMMAND - Types: REPLACE_WITH_PROJECT_COMMAND - Lint: REPLACE_WITH_PROJECT_COMMAND - Test: REPLACE_WITH_PROJECT_COMMAND - Security: REPLACE_WITH_PROJECT_COMMAND - Quality: REPLACE_WITH_PROJECT_COMMAND ## Completion - List changed files and why each was necessary. - Confirm required checks passed with exact commands. - Call out risks, assumptions, and unverified external state. - Do not claim deployment, publication, or production validation unless it happened.

Replace placeholders with repository facts

The template only becomes useful when it points to real commands and boundaries. Name the package manager. State whether integration tests require containers. Link the schema owner. Say which directory contains migrations and how to roll them back. Explain which UI states need screenshots. Include the actual threshold that fails CI.

Avoid rules that are neither testable nor illustrated. “Use best practices” forces the agent to guess. “Parse external JSON with the existing schema in src/boundary before passing it to domain services” is actionable.

Use scope, not one giant file

Monorepos and mixed-language projects need layered instructions. Put stable cross-repository expectations at the root. Place build commands, framework conventions, and safety constraints near the package or subsystem they govern. More specific files should refine the root, not repeat it.

Cursor's project rules support path-aware scope. GitHub Copilot supports path-specific instruction files. AGENTS.md implementations commonly use the nearest file in the directory hierarchy. Whatever mechanism you choose, test it with a small task and ask the agent to report which instructions it loaded.

Move repeatable prose into executable checks

If the rules say “no unused imports,” the compiler or linter should enforce it. If they say “no known vulnerable dependencies,” run a dependency scanner. If they say “every behavior change needs a test,” make the test suite and coverage change visible in the pull request.

For generated-code residue, aislop can enforce named patterns such as swallowed exceptions, unsafe assertions, narrative comments, debug leftovers, dead code, unresolved stubs, generic naming, and complexity thresholds. That turns part of the rules file from a request into a gate.

npx aislop@latest ci --changes --base origin/main

Replace the example base with the pull request's target branch. Keep the division honest: automation owns repeatable facts; the rules file supplies local context; the reviewer owns judgment and exceptions.

Maintain the standard like code

  • Review instruction changes in pull requests.
  • Add a rule only after a repeated failure or an important architectural decision.
  • Remove obsolete commands immediately; stale instructions are worse than missing ones.
  • Prefer a good example and a bad example when wording remains ambiguous.
  • Track whether the rule reduced review comments or merely added prompt length.

The best file is not the longest. It is the smallest maintained context that reliably changes agent behavior—and is backed by a gate when compliance is mechanically testable.

Sources

Frequently asked questions

What should an AI coding rules file contain?

Include project structure, exact build and test commands, architectural boundaries, code conventions, security constraints, task scope, required evidence, pull-request expectations, and which instructions apply to nested directories. Keep rules concrete and testable.

Should I use AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions?

Use the format your tools actually load, with AGENTS.md as a portable shared source where supported. Claude Code uses CLAUDE.md, Cursor supports project rules and root instruction files, and GitHub Copilot supports repository and path-specific instructions. Avoid divergent copies by generating or linking tool-specific files from one maintained standard.

Do instruction files guarantee code quality?

No. They provide context and behavioral guidance but do not prove compliance. Convert repeatable rules into formatters, type checks, tests, security scans, and deterministic quality gates, then keep instructions for repository-specific judgment and workflow.

← All posts