Root Instruction File Exists
A root instruction file must exist at the project root. This is the primary entry point for any AI coding agent.
CriticalcorestructureRules
Core rules apply to every agent; each agent adds its own.
139 rules · 5 categories · 5 agents
Filtering by
Valid Markdown Syntax
Instruction files must contain valid markdown structure. Broken or empty markdown prevents agents from parsing content correctly and can cause instructions to be silently ignored.
CriticalcorestructureHook Valid Event Types
Hook event keys in .agents/hooks.json (or the global ~/.gemini/config/hooks.json) MUST use recognized hook event type names (5 events: PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop). Unrecognized event names are silently ignored, so a typo means the hook never fires.
HighantigravitystructureHook Handler Has Type
A hook handler in .agents/hooks.json MAY set a "type" field, and when it does the value MUST be command — the only supported handler type. The docs list command as the default when "type" is omitted, so leaving it out is valid. A handler with any other type is never dispatched and the hook silently does nothing.
HighantigravitystructureHook Command Has Field
Hook handlers in .agents/hooks.json with "type": "command" — or with no "type", which defaults to command — MUST include a "command" field containing the shell command to execute. Without it, the agent has no command to run and the hook fails silently.
HighantigravitystructureHook Command Has Field
Hook handlers with "type": "command" MUST include a "command" field containing the shell command to execute. Without it, Claude Code has no command to run and the hook fails silently.
HighclaudestructureHook Valid Event Types
Hook event keys in .claude/settings.json MUST use recognized Claude Code event type names (33 events as of 2026-09-30). Unrecognized event names are silently ignored, so a typo like "PreTooluse" (lowercase u) means the hook never fires.
HighclaudestructureHook Handler Has Type
Each hook handler object in .claude/settings.json MUST contain a "type" field set to "command", "http", "mcp_tool", "prompt", or "agent". Without a type field, Claude Code cannot dispatch the handler and the hook silently does nothing.
HighclaudestructureHook Prompt Has Field
Hook handlers with "type": "prompt" or "type": "agent" MUST include a "prompt" field containing the instruction text. Without it, Claude Code has no prompt to inject and the hook does nothing.
HighclaudestructureImport Depth Within Limit
Claude Code's CLAUDE.md @import chains have a documented hard limit of 4 hops. Imports beyond depth 4 are not resolved — content past the cutoff is silently dropped. This stub supersedes the more permissive CORE ceiling with Claude's actual documented threshold so the agent-specific cap is enforced when the project is scanned with --agent claude or when Claude is auto-detected.
HighclaudestructureHook Valid Event Types
Hook event keys in .codex/hooks.json (or an inline [hooks] table in config.toml) MUST use recognized Codex event type names (12 events: SessionStart, SessionEnd, SubagentStart, SubagentStop, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, Stop, Interrupt). Unrecognized event names are silently ignored, so a typo means the hook never fires.
HighcodexstructureHook Handler Has Type
Each hook handler object in .codex/hooks.json (or an inline [hooks] table in config.toml) MUST contain a "type" field set to command or mcp_tool. Without a type field, Codex cannot dispatch the handler and the hook silently does nothing.
HighcodexstructureHook Command Has Field
Hook handlers with "type": "command" in .codex/hooks.json (or an inline [hooks] table in config.toml) MUST include a "command" field containing the shell command to execute. Without it, Codex has no command to run and the hook fails silently.
HighcodexstructurePath Scope Declared
A scoped instructions file MUST declare its file-pattern filter in frontmatter. .github/instructions/*/.instructions.md files use applyTo; VS Code Copilot also reads .claude/rules/*/.md for cross-agent compatibility, and for those files the VS Code docs say to keep Claude's own paths key instead of applyTo. Without a scope key in the file type that requires one, Copilot applies the instructions globally, which defeats the purpose of scoping and can surface irrelevant guidance in unrelated contexts.
HighcopilotstructureHook Valid Event Types
Hook event keys in .github/hooks/*.json MUST use a recognized Copilot event type name. The Copilot hooks reference accepts both the camelCase form (sessionStart, preToolUse, userPromptSubmitted, …) and its PascalCase alias (SessionStart, PreToolUse, UserPromptSubmit, …) — either casing fires the hook. An unrecognized name in neither list is silently ignored, so the hook never fires.
HighcopilotstructureHook Handler Has Type
A hook handler object in .github/hooks/*.json MAY set a "type" field to command, http, or prompt. The Copilot hooks reference states "type" defaults to "command" when omitted, so leaving it out is valid — but an explicit value outside the three recognized types is never dispatched.
HighcopilotstructureHook Command Has Field
A command hook handler in .github/hooks/*.json MUST include at least one of "bash", "powershell", "command", or "exec" with a non-empty value — the Copilot hooks reference requires one of these four to name the executable. Without one, Copilot has nothing to run and the hook fails silently. A command handler is one with "type": "command", or one that omits "type", which Copilot runs as a command.
HighcopilotstructureShallow Heading Hierarchy
Heading hierarchy must stay at 4 levels or fewer -- no ##### (h5) or deeper headings. Deep nesting makes content harder to scan and signals that the file should be split into smaller files.
HighcorestructureIdentity Fields In Frontmatter
Frontmatter must include identity fields (id, name, or slug) to uniquely identify the instruction file. Without an identity field, the file cannot be referenced, overridden, or tracked by other rules.
HighcorestructureFrontmatter Block Present
Scoped rule files must begin with a --- YAML frontmatter delimiter as the very first line. The frontmatter block provides metadata like globs and description that controls how the agent discovers and loads the rule file.
HighcorestructureImport Targets Resolve
Import references in instruction files must resolve to existing files. Broken imports create gaps in the agent's context — the agent silently skips missing files without warning.
HighcorestructureHook Valid Event Types
Config files must contain a "hooks" key. This base rule gates hook validation — agent-specific rules (Claude, Codex, Copilot, Cursor, Antigravity) supersede with checks for recognized event names per agent.
HighcorestructureHook Handler Has Type
At least one handler in the "hooks" block must carry a "type". Without a type field, the agent cannot dispatch handlers. Agent-specific rules supersede with the valid type enum per agent.
HighcorestructureHook Command Has Field
Each hook handler with "type": "command" must carry its own "command" key with a non-empty string value. The check reads every command handler on its own, so a valid command on one handler does not cover another.
HighcorestructureHook Prompt Has Field
A hook handler declared with "type": "prompt" or "type": "agent" must carry its own non-empty "prompt" field. A config with no prompt- or agent-typed handler at all draws no finding from this check — there is nothing for it to require a prompt on.
HighcorestructureImport Depth Within Limit
Import chains in root instruction files should be bounded. Deep import hierarchies increase context loading time and create fragile dependency chains; a change to a deeply nested file can silently break import resolution of files several levels up. The CORE check enforces a permissive absolute ceiling (10 hops) — agents whose @<path> syntax has a documented behavior should declare a per-agent supersede stub with the actual threshold. Of the agents currently in the registry: Claude defines a 4-hop hard limit (see CLAUDE:S:0010); Cursor's @filename is single-level only (see CURSOR:S:0006); Antigravity supports chained @file.md imports without a documented max and inherits the CORE ceiling; Codex and Copilot declare CORE:S:0033 in their config.yml excludes: because their instruction files do not honor any @<path> inclusion syntax.
HighcorestructureSkill No README
Skill directories MUST NOT contain a README.md file. All skill documentation belongs in SKILL.md — agents discover and load SKILL.md as the skill entry point. A separate README.md splits documentation across two files and the extra file is never loaded.
HighcorestructureSkill Description Present
The description field in SKILL.md YAML frontmatter MUST be present and non-empty. The description is what a host agent reads to decide whether to load a skill — it is the skill's discovery surface. A SKILL.md with no description (or an empty one) is effectively invisible: the agent cannot tell when the skill applies, so it is never invoked. Front-load the key use case in one or two sentences and keep it concise.
HighcorestructureMarkdown Link Targets Resolve
Markdown links in instruction files must resolve to existing files. Broken targets create phantom context — the agent sees the link directive but the referenced content never loads, so the file silently underdelivers compared to what its prose promises.
HighcorestructureHook Valid Event Types
Hook event keys in .cursor/hooks.json MUST use recognized Cursor event type names (21 events). Unrecognized event names are silently ignored, so a typo means the hook never fires.
HighcursorstructureHook Handler Has Type
A hook handler object in .cursor/hooks.json MAY set a "type" field to command or prompt. Cursor's docs list command as the default when "type" is omitted, so leaving it out is valid — but an explicit value other than command/prompt is never dispatched.
HighcursorstructureHook Command Has Field
Hook handlers in .cursor/hooks.json with "type": "command" — or with no "type", which Cursor runs as a command — MUST include a "command" field containing the shell command to execute. Without it, Cursor has no command to run and the hook fails silently.
HighcursorstructureHook Prompt Has Field
Hook handlers with "type": "prompt" in .cursor/hooks.json MUST include a "prompt" field containing the instruction text. Without it, Cursor has no prompt to inject and the hook does nothing.
HighcursorstructureImport Depth Within Limit
Cursor's @filename syntax in AGENTS.md and .cursor/rules/*.mdc is single-level only — referenced files are pulled into context, but @<path> syntax inside those referenced files is not transitively followed. This stub supersedes the more permissive CORE ceiling with Cursor's actual single-level model so a chained-import pattern (which Cursor does not honor) is flagged early.
HighcursorstructureMemory File Within Size Limit
MEMORY.md should stay under the host agent's memory truncation threshold. Claude Code loads only the first 200 lines or 25KB of MEMORY.md (whichever comes first); content past either cutoff is silently dropped from the agent's context. Other agents that adopt a memory surface may set different caps. Keep the index concise — store detail in linked memory files, not inline.
MediumclaudestructurePath Scope Declared
Claude Code path-scoped rules must declare a paths frontmatter key. The code reads frontmatter.paths internally — the globs key is not read and rules using it silently load without path scoping. Only paths is processed; other frontmatter keys are silently ignored.
MediumclaudestructureOverride Read Order
Codex discovers instruction files in a specific order: AGENTS.override.md first, then AGENTS.md, then fallback filenames — walking from the project root to the current working directory. Document this discovery chain so users understand which file takes precedence and where to put overrides.
MediumcodexstructureSettings Scope Declared
A Codex configuration file's scope (project or user) is fixed by which path it lives at, so config.toml must declare real settings rather than ship as an empty placeholder. An empty file leaves the agent unable to tell whether the config is unused, mid-setup, or broken.
MediumcodexstructureHook Event Handlers
A "hooks" block in .github/hooks/*.json must list at least one handler under an event. A handler names what it runs: a "type", or one of "bash", "powershell", "command", or "exec". Copilot runs a handler with no "type" as a command, so { "bash": "./scripts/guard.sh" } is a complete handler. A file with no "hooks" key is not this rule's concern.
MediumcopilotstructureSection Headers Present
The agent's main instruction file must contain markdown section headers (lines starting with #). Headers organize content into navigable sections that help agents locate relevant instructions.
MediumcorestructureExact Filename Convention
Instruction filenames must contain only alphanumeric characters, dots, underscores, and dashes — matching the pattern ^[A-Za-z0-9._-]+$. This prevents encoding issues, shell escaping problems, and path resolution failures across platforms.
MediumcorestructureExpected Directories Exist
Configuration files referenced by instruction files must exist on disk. The check verifies that at least one config-type file is present, serving as a gate for directory structure validation.
MediumcorestructureModular File Organization
A project must contain at least 2 instruction files. Splitting instructions across multiple files keeps each file focused and prevents a single monolithic document from growing unwieldy.
MediumcorestructureChild Nested Instructions
Child instruction files must extend their parent's scope without contradicting it. Contradictions between levels create confusion.
MediumcorestructureAgent Documents Filenames
The main instruction file must document which instruction filenames its agents read and in what priority order.
MediumcorestructureScope Fields In Frontmatter
Scoped instruction files must declare their scope boundary in frontmatter using scope:, globs:, or applies_to: fields. Without a declared scope, the file's targeting is ambiguous and the agent cannot determine which files the instructions apply to.
MediumcorestructureDescriptive Filenames
Scoped rule files must use lowercase kebab-case filenames ending in .md, .mdc, .yml, or .yaml. Consistent naming lets developers predict file content from the filename and prevents platform-specific path issues.
MediumcorestructureSkill Entry Point Present
Every directory under a skills root (e.g. .claude/skills/<name>/) must contain a SKILL.md file. SKILL.md is the entry point the agent's skill loader uses to discover and invoke a skill — a skill directory without it is invisible to the agent.
MediumcorestructureLayered Content Structure
The agent's main instruction file must be organized with at least two top-level headings for major topics. This lets the agent quickly find relevant sections instead of scanning a flat wall of text.
MediumcorestructureSkill Directory Kebab Case
Skill files must declare a name: field in frontmatter using kebab-case format (lowercase letters and digits separated by hyphens). Consistent naming prevents path resolution errors across platforms.
MediumcorestructureSingle Topic Per Section
The agent's main instruction file must have layered structure with at least 3 headings. Sufficient heading count indicates that content is split into focused sections rather than lumped under one or two broad headings.
MediumcorestructureHook Event Handlers
A config file that declares a "hooks" block must give at least one handler a "type". A "hooks" block with no typed handler leaves the agent with a section that names nothing it can act on. A config file with no "hooks" key at all is not this rule's concern — it has not declared hooks, so there is nothing to check.
MediumcorestructureSettings Scope Declared
A configuration file's scope (project, user, local, or managed) is fixed by which path it lives at, so the file itself must declare real settings rather than ship as an empty placeholder. An empty config leaves the agent unable to tell whether the file is unused, mid-setup, or broken.
MediumcorestructureAgent Memory Directory
Agent memory must be stored in a dedicated directory, separate from instruction content.
MediumcorestructureRules Directory Structure
When scoped rule files exist, they must reside in the expected directory for the agent (e.g., .claude/rules/). This ensures the agent discovers and loads rules correctly at session start.
MediumcorestructureImport References Resolve
Every @path import reference in an instruction file must resolve to an existing file. Broken import references create phantom context — the agent sees the import directive but the referenced content never loads, causing silent gaps in its instruction set.
MediumcorestructureSkill File Length
Skill entry point files must stay under 500 lines. Agents load the full SKILL.md body into context on activation. Long skill files consume context budget and displace conversation history. Move detailed reference material to separate files in the skill directory.
MediumcorestructureSkill Name Matches Directory
The name field in SKILL.md YAML frontmatter MUST match the containing directory name in kebab-case. Skill loaders use the directory name for discovery and the frontmatter name for display — a mismatch causes the skill to be invocable under one name but displayed under another.
MediumcorestructureSubdirectory Instruction Files
Subdirectory instruction files must contain directive content -- actionable instructions the agent can follow. Files without directives or constraints waste the agent's context window without providing guidance.
MediumcorestructurePath Scope Declared
Path-scoped instruction files must declare which paths they apply to via a frontmatter key. Without a scope declaration, the file loads for all contexts instead of being scoped to specific files.
MediumcorestructureHeading As Instruction
Headings should organize content into sections, not carry instructions. The model processes heading content the same as body content, but instructions in headings are structurally fragile — they get lost when files are reorganized, and they can't carry the detail an instruction needs.
MediumcorestructureSubagent Frontmatter Identity
A subagent definition (.claude/agents/<name>.md) must declare both name and description in its YAML frontmatter. The Claude Code subagent contract lists both as required fields: name is the unique identifier the dispatch handle and hooks (agent_type) resolve against, and description is the text the model reads to decide when to delegate. A subagent missing description is never auto-selected for a task; one missing name cannot be addressed deterministically. Declare both so the harness loads and routes the subagent instead of silently ignoring it.
MediumcorestructurePlugin Manifest Required Keys
A plugin manifest (.claude-plugin/plugin.json) must declare name and description. name is the plugin's unique identifier and the namespace every bundled skill is prefixed with (/<name>:<skill>); description is the text shown in the plugin manager when browsing or installing. A manifest missing name has no namespace to mount its skills under; one missing description shows blank in the manager. version and author are optional. Declare name and description so the plugin installs and displays.
MediumcorestructurePath Scope Declared
Cursor path-scoped .mdc rules must declare a globs frontmatter key. Rules without globs and without alwaysApply: true are manual-only (loaded via @-mention, not automatically).
MediumcursorstructureHook Event Handlers
A "hooks" block in .cursor/hooks.json must list at least one handler under an event. A handler names what it runs: a "command", or "type": "prompt" with a "prompt". Cursor runs a handler with no "type" as a command, so { "command": "./.cursor/hooks/format.sh" } is a complete handler. A file with no "hooks" key is not this rule's concern.
MediumcursorstructureRule File Length Limit
Keep .claude/rules/*.md files under 200 lines. This is best-practice guidance rather than a documented Claude Code limit — Claude Code does not truncate rule files at any length. The 200-line ceiling is a soft cap that works in concert with the topic-focus rules: when a rule file keeps each topic in its own section (CORE:S:0019 single-topic-per-section) and does not restate topics another loaded file already covers (CORE:C:0044 topic-overlap), 200 lines is comfortably enough to cover that scope with concrete examples and constraints. Files that exceed the cap usually betray topic fragmentation, redundant restatement, or examples that belong in referenced project files rather than inline. Long rule files also compete for attention with other context — every line is loaded into the agent's context window at session start, so density wins over breadth.
LowclaudestructureSkill OpenAI YAML
Codex reads optional per-skill metadata — a display name, an icon, and an invocation policy — from a settings file in the skill directory. Without it, the skill shows with no name or icon in the Codex UI, and cannot be triggered implicitly.
LowcodexstructureSetup Steps Defined
A Copilot Coding Agent project that ships .github/workflows/copilot-setup-steps.yml SHOULD define its job with the exact id copilot-setup-steps. The docs state the job "MUST be called copilot-setup-steps or it will not be picked up by Copilot" — any other job id in that file is silently ignored, and the agent starts working without the environment the workflow was meant to prepare.
LowcopilotstructureSelf Contained Skills
Skill files should carry at least one structural heading — Input, Process, Output, Constraints, or an equivalent (Steps, Workflow, Prerequisites, Requirements, Result, Limitations) — so the skill is scannable and gives the agent what it needs without hunting through other files. The skill file format itself mandates no fixed section set; this rule nudges toward some structure, it does not require a specific four-heading layout.
LowcorestructureLocal Override File
A local override file, when present, should contain at least 20 characters of substantive content. Override files allow user-specific customizations without modifying committed instruction files. The override file is optional — not all projects need user-specific overrides.
LowcorestructureSpecificity Gap
Instructions must name concrete constructs -- backtick-wrapped tokens, file paths, function names, CLI commands -- instead of abstract concepts. Abstract instructions are dramatically less effective because the model cannot distinguish them from general knowledge.
CriticalcorecoherenceSpecificity Shields Against Competition
Directives in prose-heavy files must name specific constructs to resist topic competition. A vague directive surrounded by prose on the same topic can degrade, while a named directive tends to hold compliance. The naming shield protects directives you want followed. It does not protect prohibitions: naming a forbidden construct anchors it instead of shielding it, so state prohibitions as abstract categories.
CriticalcorecoherenceThe Ideal Instruction
An instruction competes for attention against everything else in context. The strongest instructions dominate; weak instructions are effectively invisible.
CriticalcorecoherenceNo Inline Style Rules
Instruction files must not use agent-specific rendering directives like inline styles or scripts.
HighcorecoherenceCross Agent Compatibility
Multi-agent projects must have compatible instruction sets — shared instructions must be agent-neutral, with agent-specific content isolated to dedicated files.
HighcorecoherenceNo Ephemeral Content
Instruction files must not contain ephemeral markers like TODO, FIXME, or WIP. These indicate incomplete content that shouldn't be committed.
HighcorecoherenceNo Auto Generated Boilerplate
Instruction content must be human-authored, not auto-generated boilerplate. Generated content lacks the project-specific context that makes instructions useful.
HighcorecoherenceAgent Neutral Main File
The main instruction file must not contain agent-specific directives. Agent-specific syntax belongs in dedicated agent files, not the shared root.
HighcorecoherenceDirectory Layout Documented
The main instruction file must document the project's directory layout. This is satisfied by either a heading such as "Structure", "Architecture", "Layout", or "Directory", or a visible tree listing / path references (src/, tests/, tree-drawing characters). Without a visible directory map, the agent cannot reliably locate or place files.
HighcorecoherenceNo Cross-File Duplication
Duplicated instructions across files drift into contradiction as one copy is updated and the other is not. Conflicting instructions severely degrade compliance. However, same-topic reinforcement using different wording is beneficial — distinct instructions that push in the same direction help each other.
HighcorecoherenceModality Weakness
Hedged instructions ("should", "try to", "consider", "prefer") couple significantly weaker than direct instructions ("do not", bare imperatives).
HighcorecoherenceRelevance Decay
Instructions are only effective for tasks they're semantically related to. A testing instruction has no effect on documentation tasks — the instruction must be relevant to the work at hand.
HighcorecoherenceSame-Topic Reinforcement and Conflict
Multiple instructions on the same topic must agree in direction. Conflicting instructions on the same topic destroy compliance catastrophically -- the model cannot follow both and may follow neither.
HighcorecoherenceScope-Instruction Conflict
Conditional scopes must not name domains whose conventions contradict the instruction. A scope that activates domain knowledge conflicting with the directive makes the instruction less effective than having no scope at all.
HighcorecoherenceCompound Weakness
Multiple weaknesses in the same instruction compound — an instruction that is hedged AND abstract AND buried early in the file is far weaker than one with any single issue. The effect is multiplicative, not additive.
HighcorecoherenceDefault Behavior Competition
The model always has a default behavior for any task — what it does without instructions. When instructions conflict or are too weak, the model reverts to this default completely. The default is an ever-present competitor.
HighcorecoherenceAmbiguous Phrasing
A sentence that uses instruction-shaped words — "never", "must", "always", "use" — but is written as a description of a fact or a requirement, rather than a command to the agent, does not get treated as an instruction. The agent reads it as background, not as something to follow, so it has no effect on behavior even though it looks like it should.
HighcorecoherenceTesting Framework Documented
The instruction file must contain a heading matching testing terms (Testing, Tests, or Test). Documenting the testing framework tells the agent which tool to use, where tests live, and how to run them.
MediumcorecoherenceWorkflow Definitions
The instruction file must contain a heading matching workflow terms (Workflow, Process, Pipeline, or Steps). Defining repeatable workflows with ordered steps helps the agent follow consistent processes for common tasks.
MediumcorecoherenceValidation Commands Present
The instruction file must contain a heading matching validation terms (Validation, Verify, QA, Lint, or Check). Documenting validation commands tells the agent which quality gates to run before committing.
MediumcorecoherenceBuild And Test Commands
The instruction file must include build and test commands that the agent can run. Without these, the agent can't verify its own changes work correctly.
MediumcorecoherenceSecurity Requirements
The instruction file must contain a section with a heading matching security-related terms (Security, Boundaries, Sensitive, or Access). Without documented security requirements, the agent has no guidance on sensitive files, access restrictions, or security patterns.
MediumcorecoherenceCoding Conventions
The instruction file must specify coding conventions — formatting tools, linting rules, and style preferences. Without these, the agent produces code that doesn't match the project's standards.
MediumcorecoherenceProject Description Present
The root instruction file must describe the project — what it does and who it's for. This anchors the agent's understanding of context and purpose.
MediumcorecoherenceAgent Role Defined
The instruction file must define the agent's role and primary function. Without a clear identity, the agent defaults to generic behavior that doesn't match the project's needs.
MediumcorecoherenceCode Block Examples Present
The instruction file must contain fenced code blocks with concrete examples. Code blocks are the clearest way to show the agent exact syntax and patterns.
MediumcorecoherenceExplicit Prohibitions
The agent's main instruction file must contain at least one prohibition — a sentence that tells the agent what NOT to do. Without explicit prohibitions, the agent defaults to its training priors, which may include destructive actions like force-pushing, deleting files, or modifying sensitive configurations.
MediumcorecoherenceCommand Workflow Documented
The instruction file must document command workflows — ordered sequences of steps for common operations like building, testing, and deploying.
MediumcorecoherenceSafety Gate Directives
The agent's main instruction file must contain safety directives using keywords like never, must not, or always. Without hard boundaries, the agent has no guardrails for dangerous operations.
MediumcorecoherenceDomain Terminology Used
Instruction files must include a section with a heading matching "Terminology", "Glossary", "Terms", or "Domain" that defines project-specific vocabulary. Defining terms prevents the agent from misinterpreting domain-specific words that have different common meanings.
MediumcorecoherenceOutput Format Specified
Instruction files must contain a heading referencing Output, Format, or Display. Specifying expected output formats tells the agent what shape its responses should take.
MediumcorecoherenceMcp Configuration Documented
The main instruction file must contain a heading referencing MCP, Server, or Tools. If the project uses MCP tools, documenting them in the main file ensures the agent discovers available servers at session start.
MediumcorecoherenceArchitecture Overview Present
The root instruction file must describe the project's architecture. The agent needs to know where major components live to navigate the codebase and make informed changes.
MediumcorecoherenceTech Stack Declared
The root instruction file must contain a heading matching technology terms (Stack, Tech, Language, Runtime, or Framework). Declaring the tech stack prevents the agent from guessing or suggesting incompatible technologies.
MediumcorecoherenceCritical Instructions at Edges
Freeform instruction files must contain at least one directive instruction. Files without directives contribute no actionable guidance and cannot benefit from position-based ordering.
MediumcorecoherenceInstruction Rationale Present
The default pattern for instructions is a directive or imperative followed by brief context within a focused length. When you need to suppress a behavior, use the golden pattern: directive first, brief positive context, then constraint last. You don't need a constraint for every directive — add constraints only when your goal is to explicitly prevent something.
MediumcorecoherenceTopic Overlap Across Elements
Give each topic one home. When two instruction files that can load in the same session both carry instructions on the same topic, the project has two sources of truth for it. The copies drift apart as one is edited and the other is not, and the agent then reads guidance that disagrees with itself. Keep the shared instructions in the file that owns the topic, and point to them from the other.
MediumcorecoherenceDescription Coherence
Files that the agent loads on demand — skills, subagents, slash commands — are dispatched by their frontmatter description: field. The agent reads the description first, decides whether the file applies, and only then loads the body. When the description names a narrower concept than the body covers, or when the description and the body are about different topics altogether, the agent never invokes the file for the cases it actually contains.
MediumcorecoherenceSubagent Tools Field Canonical
A subagent definition restricts its tools with the tools field (an allow-list) or the disallowedTools field (a deny-list). It does not use allowed-tools — that is the skill (SKILL.md) field. A subagent frontmatter declaring allowed-tools: (or the non-existent allowedTools:) is silently ignored by the harness: the intended restriction never applies and the subagent inherits every tool. Name the restriction with tools: so the allow-list actually binds.
MediumcorecoherenceSkill Invocation Reachable
A skill must stay invocable by someone. Two SKILL.md frontmatter gates control who can invoke it: disable-model-invocation: true stops the model from auto-invoking (only the user can, via /name), and user-invocable: false hides it from the / menu (only the model can invoke it). Setting both makes the skill unreachable — the model cannot invoke it and neither can the user, so the skill is dead config that loads for no path. Set at most one of the two gates so at least one invoker remains.
MediumcorecoherenceOne Instruction Per Sentence
Give each instruction its own sentence. Instructions packed into one sentence compete, and some of them are not followed; the last one tends to win. The joining punctuation does not change that, because a comma, a semicolon, a dash, "and" or "then" packs instructions the same way. A period or a list item of its own is what separates them. When two instructions must share a sentence, put the one that must win last.
MediumcorecoherenceBroad Conditional Scope
An instruction that opens with a condition ("When...", "If...", "Unless...", "Before...", "After...") should name the specific situation it applies to. A condition that names outside systems — "external", "third-party", "service(s)", "integration(s)", "dependency" / "dependencies", "database", "SQL" — covers far more ground than the instruction's author likely intended, so the agent applies the instruction in situations no one checked. Wide but harmless wording such as "any file" or "all tests" is not reported.
MediumcorecoherenceStable Content First
The agent's main instruction file must separate stable instructions from frequently-changing content using distinct sections. Stable content (identity, tool names, permanent constraints) should come first. Dynamic content (session-specific guidance, mutable configuration) should come later. The last positions in a file carry the strongest attention weight — placing dynamic content toward the end means updates land in high-attention positions without disrupting stable instructions above.
LowcorecoherenceFlowcharts for Procedures
Branching workflows read more clearly as a flowchart. When an instruction file spells out a multi-step procedure as a numbered list laced with conditional language ("if", "when", "otherwise"), the rule flags it as a candidate for a mermaid diagram. Files with no branching procedure are never flagged — the rule fires only where a branching numbered list is actually present, not on the mere absence of a diagram.
LowcorecoherenceContent Dilution
Same-topic prose can compete with your instruction on that topic: prose and directive share the attention that topic draws, so descriptive same-topic content can pull attention away from the directive. A little context costs little; large volumes can pull enough away to blunt the instruction.
LowcorecoherencePosition Recency
A prohibition that names exactly what it forbids, placed early among instructions on unrelated subjects, is easily lost: the instructions after it outweigh it, and naming the forbidden thing draws attention to it rather than protecting the constraint.
LowcorecoherenceDirection Imbalance
Directives and constraints within the same topic must have balanced strength. When prohibitions are written more strongly than enabling instructions, the agent may suppress the intended behavior entirely rather than conditionally gating it.
HighcoredirectionInstruction Ordering
Within a topic, the ORDER of instructions matters. Putting the directive first, reasoning between, and the constraint last is significantly more effective than the natural human pattern of leading with prohibitions.
HighcoredirectionDirective Density
Instruction files must contain at least one directive — a sentence that tells the agent what to do using imperative or absolute wording. Files with only descriptive prose and no actionable directives have no behavioral effect on the agent.
MediumcoredirectionAGENTS.md Within Size Limit
Codex caps the combined AGENTS.md instruction chain — global ~/.codex/AGENTS.md plus every AGENTS.md from the git root down to the working directory — at 32 KiB (32,768 bytes) by default, the project_doc_max_bytes setting. Content past the cap is silently truncated and never reaches the model, with no warning. Keep the eager AGENTS.md footprint under 32 KiB, or raise project_doc_max_bytes deliberately when you need more.
HighcodexefficiencyTotal Instruction Size Limit
The always-injected ("one round") instruction footprint should stay under 100 KB (102,400 bytes). This counts what the agent loads every turn: eager instruction files (the main file + its imports + the memory index) in full, and progressive-disclosure surfaces (skills, subagents) by their name + description metadata only. On-demand rules, recalled memory entries, and skill / agent bodies load only when needed and are not counted. A bloated always-on footprint wastes context budget every turn and dilutes every instruction it carries.
LowcoreefficiencyInstruction File Size Limit
Individual instruction files must stay within size limits. Oversized files exceed context windows and degrade agent performance. The check enforces a maximum of 300 lines per file.
LowcoreefficiencyFormatting Effectiveness
Use backtick for code identifiers whether the sentence is a directive or a prohibition. Bold draws the model's attention to the wrapped term. Inside a prohibition, that spotlights the forbidden concept — the opposite of what you want — so carry the constraint in italic instead. On a positive directive, bold spotlights the behaviour you DO want, so it is not penalized.
LowcoreefficiencyInstruction Elaboration
Instructions with too few words are effectively invisible. The strongest instruction is one compact sentence that names the specific tool, file, or command it applies to.
LowcoreefficiencyRelated Instructions Grouped
The agent's main instruction file must group related instructions by topic into their own sections, rather than scattering a topic's directives across the file — grouping by topic keeps each directive near the context that makes it relevant. But grouping is not cramming: directives packed tightly together compete hardest for attention, since the closer two directives sit the more they draw from the same share. Group BY TOPIC; do not simply co-locate everything.
LowcoreefficiencyItalic Constraints
Prohibitions should be wrapped entirely in italic markdown. Full-sentence italic visually marks a prohibition, separating it from the directive and the reasoning that precede it.
LowcoreefficiencySubagent System Prompt No Secrets
A subagent definition (.claude/agents/<name>.md) must not embed a credential, API key, password, or private key in its frontmatter or system-prompt body. A subagent file is committed instruction text loaded into an agent's context; a secret written there leaks into version control and into every session that dispatches the subagent. Reference secrets through environment variables or a secret store the tool reads at runtime, never as a literal in the prompt.
HighcoregovernanceHook Uses Project Dir Variable
Hook shell commands SHOULD anchor their paths instead of hardcoding absolute ones: a project hook with $CLAUDE_PROJECT_DIR (or $CLAUDE_ENV_FILE), a plugin's hook with ${CLAUDE_PLUGIN_ROOT} (or ${CLAUDE_PLUGIN_DATA}). Claude Code injects these environment variables at runtime — using them makes hooks portable across machines and collaborators.
MediumclaudegovernancePermission Config Declared
Codex configuration must declare its access policy. Codex has no permissions block; it controls access through approval_policy (when Codex asks before acting) and sandbox_mode (what Codex may touch). A config.toml that sets neither leaves access entirely to the host defaults, so nothing in the project records what the agent may do. Setting either key makes the access policy visible and reviewable in the repository.
MediumcodexgovernancePermission Config Denies Sensitive
Codex has no deny list. It keeps secrets, credentials, and private keys out of reach through its sandbox, which stays on unless the configuration turns it off. A config.toml must therefore not set sandbox_mode = "danger-full-access", the value that disables sandboxing entirely.
MediumcodexgovernanceVcs Tracked
All instruction files must be tracked in git. Untracked instruction files create divergence between collaborators -- each developer's agent sees different instructions.
MediumcoregovernanceNo Credentials
Instruction files must never contain credentials, API keys, or private keys. Secrets in instruction files get committed to version control.
MediumcoregovernancePermission Config Declared
Agent configuration must declare an explicit permission block. A config with no permissions section leaves access entirely to the host defaults, so nothing in the project records which tools and paths the agent may touch. Declaring the block — even a minimal one — makes the access policy visible and reviewable in the repository.
MediumcoregovernanceForbidden Commands Defined
The main instruction file must contain at least one prohibition that rules out an abstract category of dangerous operation. Bounding destructive operations as a category prevents the agent from force-pushing, deleting files, or mutating the database without explicit user approval.
MediumcoregovernancePermission Config Denies Sensitive
A configuration file must declare a non-empty "permissions.deny" list. Without an explicit denial, the agent may read or write secrets, credentials, and private keys.
MediumcoregovernanceHook Uses Project Dir Variable
Hook commands must not contain hardcoded absolute paths like /home/user/project/. The check flags each hook handler whose "command" starts with a common Unix/macOS base directory. Agent-specific rules supersede with checks for the correct project dir variable per agent.
MediumcoregovernanceProject Config Self Contained
Project configuration must be self-contained — no dependencies on user-specific setup or external state not documented in the project.
MediumcoregovernanceMcp Config Declares Servers
The file an agent actually reads for MCP servers must declare at least one. Claude Code reads project-scope servers from .mcp.json and user-scope servers from ~/.claude.json — not from settings.json, which has no mcpServers key at all. Each agent's own MCP surface is declared under that agent's mcp file type; this rule follows that surface, whatever file it names. Without a declared entry, the agent has no record of which MCP tools are available or how they are scoped.
MediumcoregovernanceHook Uses Project Dir Variable
Hook commands in .cursor/hooks.json SHOULD NOT hardcode an absolute path such as /home/user/project/.... Cursor runs project hooks from the project root, so a path relative to the root (.cursor/hooks/lint.sh) works on every machine and clone. When a command needs the root explicitly, use $CURSOR_PROJECT_DIR, or its alias $CLAUDE_PROJECT_DIR — Cursor sets both on every hook run.
Mediumcursorgovernance