Section Headers Present
Each instruction file must contain markdown section headers (lines starting with #). Headers organize content into navigable sections that help agents locate relevant instructions.
CriticalcorestructureRules
Filtering by
Structure
65 rulesRoot Instruction File Exists
A root instruction file must exist at the project root. This is the primary entry point for any AI coding agent.
CriticalcorestructureValid 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 .gemini/settings.json MUST use recognized hook event type names (11 events). Unrecognized event names are silently ignored, so a typo means the hook never fires. Antigravity keeps the Hooks surface from Gemini CLI; the event-type set here is inherited pending published Antigravity hook docs.
HighantigravitystructureHook Handler Has Type
Each hook handler object in .gemini/settings.json MUST contain a "type" field set to command. The inherited Gemini-CLI hooks contract supports only command. Without a type field, the agent cannot dispatch the handler and the hook silently does nothing.
HighantigravitystructureHook Command Has Field
Hook handlers with "type": "command" in .gemini/settings.json 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 (29 events as of 2026-04-29). 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 5 hops. Imports beyond depth 5 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 MUST use recognized Codex event type names (6 events). 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 MUST contain a "type" field set to command. 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 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
Scoped .github/copilot-instructions.md files MUST include an applyTo field in their YAML frontmatter to declare which file patterns the instructions target. Without applyTo, Copilot applies the instructions globally, which defeats the purpose of scoped instruction files and can cause irrelevant guidance to appear in unrelated contexts. The slug aligns with the path-scope-declared family used by Claude (paths:) and Cursor (globs:); Copilot's frontmatter key is applyTo: per the VS Code Copilot docs.
HighcopilotstructureHook Valid Event Types
Hook event keys in .github/hooks/*.json or VS Code hook config MUST use recognized Copilot event type names. The VS Code Copilot doc lists eight events in PascalCase: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop. Unrecognized event names — including camelCase variants like preToolUse — are silently ignored, so the hook never fires.
HighcopilotstructureHook Handler Has Type
Each hook handler object in .github/hooks/*.json or VS Code hook config MUST contain a "type" field set to command. The VS Code Copilot hooks reference states each hook entry must have type: "command". Without a type field, Copilot cannot dispatch the handler and the hook silently does nothing.
HighcopilotstructureHook Command Has Field
Hook handlers with "type": "command" in .github/hooks/*.json or VS Code hook config MUST include a "command" field containing the shell command to execute. Without it, Copilot has no command to run and the hook fails silently.
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.
HighcorestructureExact 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.
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
\n<key>: <value>\n---\n lines. The block declares the file's identity (name, description) and scope (paths, loading, maintainer`) so the loader can target it correctly. ---
HighcorestructureExpected 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.
HighcorestructureModular 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.
HighcorestructureDescriptive Filenames
Scoped rule files must use lowercase kebab-case filenames ending in .md, .yml, or .yaml. Consistent naming lets developers predict file content from the filename and prevents platform-specific path issues.
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
Hook configuration must contain at least one "type" key. Without a type field, the agent cannot dispatch handlers. Agent-specific rules supersede with the valid type enum per agent.
HighcorestructureHook Command Has Field
Hook configuration must contain at least one "command" key with a non-empty string value. The check scans for "command": "..." anywhere in the config file.
HighcorestructureHook Prompt Has Field
Hook configuration must contain at least one "prompt" key with a non-empty string value. The check scans for "prompt": "..." anywhere in the config file.
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 5-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 Length
The description field in SKILL.md YAML frontmatter MUST be present and concise. The Agent Skills open standard at agentskills.io caps the field at 1024 characters, and GitHub Copilot enforces the same 1024-character cap explicitly. Claude Code caps the combined description + when_to_use text at 1,536 characters in the skill listing. Codex bounds the entire skill list (not the individual description) at roughly 2% of the model context window or 8000 characters. Cursor and Antigravity do not document a hard cap but follow the open standard. A description that respects 1024 characters is portable across every agent; long descriptions waste context tokens and risk truncation in the agents that enforce the tighter cap. Front-load the key use case.
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 (20 events). Unrecognized event names are silently ignored, so a typo means the hook never fires.
HighcursorstructureHook Handler Has Type
Each hook handler object in .cursor/hooks.json MUST contain a "type" field set to command or prompt. Without a type field, Cursor cannot dispatch the handler and the hook silently does nothing.
HighcursorstructureHook Command Has Field
Hook handlers with "type": "command" in .cursor/hooks.json 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.
MediumcodexstructureChild Nested Instructions
Child instruction files must extend their parent's scope without contradicting it. Contradictions between levels create confusion.
MediumcorestructureAgent Documents Filenames
Agent configuration must document which instruction filenames it checks 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.
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
Instruction content 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 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
Config files that define hooks or event handlers must include a heading matching Hook, Event, Trigger, or Pre-commit. Without a labeled section, trigger conditions are buried in unstructured content where they are easy to miss.
MediumcorestructureSettings Scope Declared
Configuration files must contain a heading matching scope-related terms (Settings, Scope, or Configuration). Declaring scope level ensures the agent knows whether settings apply project-wide, per-user, or are system-managed.
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.
MediumcorestructurePath Scope Declared
Cursor path-scoped rules must declare a globs frontmatter key. Rules without globs and without alwaysApply: true are manual-only (loaded via @-mention, not automatically).
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 follows CORE:C:0044 topic-scatter (one or two topics per file) and CORE:S:0019 single-topic-per-section (each topic in its own section), 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 skill directories SHOULD contain an agents/openai.yaml file with display_name, icon, and invocation policy fields. This metadata controls how the skill appears in the Codex UI and whether it can be triggered implicitly.
LowcodexstructureSetup Steps Defined
Copilot Coding Agent projects SHOULD define a steps: array in their configuration to specify workspace setup commands. These steps run before the agent starts working — without them, the agent may fail on projects that require dependency installation, database setup, or build steps.
LowcopilotstructureSelf Contained Skills
Skill files must include headings matching Input, Process, Output, and Constraints. A self-contained skill gives the agent everything it needs to execute the task without hunting through other files.
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.
LowcorestructureCoherence
42 rulesSpecificity 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.
CriticalcorecoherenceTopic Scatter
Instruction files must focus on 1-2 topics. Instructions spanning multiple unrelated topics compete for attention, degrading compliance on all topics -- while same-topic instructions reinforce each other.
CriticalcorecoherenceSame-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.
CriticalcorecoherenceSecurity 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.
HighcorecoherenceCoding 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.
HighcorecoherenceProject 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.
HighcorecoherenceAgent 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.
HighcorecoherenceNo Inline Style Rules
Instruction files must not use agent-specific rendering directives like inline styles or scripts.
HighcorecoherenceExplicit Prohibitions
Instruction files must contain at least one constraint atom — 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.
HighcorecoherenceDomain 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.
HighcorecoherenceOutput 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.
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.
HighcorecoherenceArchitecture 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.
HighcorecoherenceTech 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.
HighcorecoherenceDirectory Layout Documented
The main instruction file must include a section documenting the project's directory layout using a heading like "Structure", "Architecture", "Layout", or "Directory" and containing a tree listing or path references. Without a visible directory map, the agent cannot reliably locate or place files.
HighcorecoherenceCritical 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.
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.
HighcorecoherenceContent Dilution
Descriptive prose on the same topic as your instructions competes for attention. Small amounts of context help, but large amounts dilute the instruction's effect. Off-topic content is harmless regardless of volume.
HighcorecoherenceModality Weakness
Hedged instructions ("should", "try to", "consider", "prefer") couple significantly weaker than direct instructions ("do not", bare imperatives).
HighcorecoherencePosition Recency
Instructions at the end of a multi-instruction context dominate. Instructions at the beginning are dramatically weak.
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.
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.
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.
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 instruction file must contain constraint atoms -- safety directives using keywords like NEVER, MUST NOT, or ALWAYS. Without hard boundaries, the agent has no guardrails for dangerous operations.
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.
MediumcorecoherenceStable Content First
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.
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.
MediumcorecoherenceRelevance 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.
MediumcorecoherenceConditional Scope
Conditional instructions ("When X, do Y") are not uniformly weaker than unconditional ones. The "When X" scope text activates the model's knowledge about what's conventional in that domain. If the convention aligns with the instruction, the scope helps. If it conflicts, the scope actively hurts.
MediumcorecoherenceSpecificity 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 degrades severely, while a named directive holds 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.
MediumcorecoherenceDefault 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.
MediumcorecoherenceThe Ideal Instruction
An instruction competes for attention against everything else in context. The strongest instructions dominate; weak instructions are effectively invisible.
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.
MediumcorecoherenceFlowcharts for Procedures
Instruction files with branching workflows must include mermaid flowcharts. Numbered lists that contain conditional language ("if", "when", "otherwise") without an accompanying mermaid block indicate a procedure that would be clearer as a diagram.
LowcorecoherenceDirection
3 rulesDirective Density
Instruction files must contain at least one directive atom — a sentence that tells the agent what to do using imperative or absolute modality. Files with only descriptive prose and no actionable directives have no behavioral effect on the agent.
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.
HighcoredirectionDirection 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.
MediumcoredirectionEfficiency
7 rulesAGENTS.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.
HighcodexefficiencyInstruction 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.
HighcoreefficiencyInstruction Elaboration
Instructions with too few tokens are effectively invisible. Instructions padded with generic filler are weaker than shorter, specific ones. The ideal instruction uses multiple DISTINCT relevant terms — each naming a different concrete aspect of the desired behavior.
HighcoreefficiencyTotal 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.
MediumcoreefficiencyRelated Instructions Grouped
Related instructions must be grouped together, not scattered across the file. Co-location reduces the agent's search effort.
MediumcoreefficiencyItalic Constraints
Constraint instructions (-1 charge) should be wrapped entirely in italic markdown. Full-sentence italic signals the charge type visually, separating the constraint from the directive (+1) and reasoning (0) that precede it.
MediumcoreefficiencyFormatting Effectiveness
Use backtick for code identifiers and italic for emphasis instead of bold on terms inside constraints. Bold draws the model's attention to the wrapped term — on a constraint, that means drawing attention to the prohibited concept.
LowcoreefficiencyGovernance
10 rulesVcs Tracked
All instruction files must be tracked in git. Untracked instruction files create divergence between collaborators -- each developer's agent sees different instructions.
HighcoregovernanceHook Uses Project Dir Variable
Hook shell commands SHOULD reference $CLAUDE_PROJECT_DIR or $CLAUDE_ENV_FILE instead of hardcoded absolute paths. Claude Code injects these environment variables at runtime — using them makes hooks portable across machines and collaborators.
MediumclaudegovernanceNo Credentials
Instruction files must never contain credentials, API keys, or private keys. Secrets in instruction files get committed to version control.
MediumcoregovernancePermissions Ordered
Permission declarations in agent configuration must follow a deterministic order — deny rules before allow rules, specific patterns before broad wildcards. First-match-wins semantics in permission evaluation mean ordering determines which rule fires. A broad allow: Bash() before a specific deny: Bash(rm -rf ) silently permits the dangerous command.
MediumcoregovernanceForbidden Commands Defined
The main instruction file must contain at least one constraint atom that prohibits specific commands or actions. Listing forbidden operations prevents the agent from executing destructive commands like git push --force, rm -rf, or database mutations without explicit user approval.
MediumcoregovernancePermission Config Denies Sensitive
Configuration files must contain at least one constraint instruction that restricts access to sensitive files. 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 "command" values that start with common Unix/macOS base directories. 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
Config files must contain a heading referencing MCP or mcpServers. Without declared server entries, the agent has no record of which MCP tools are available or how they are scoped.
MediumcoregovernanceHook Uses Project Dir Variable
Hook shell commands in .cursor/hooks.json SHOULD reference $CURSOR_PROJECT_DIR instead of hardcoded absolute paths. Cursor injects this environment variable at runtime — using it makes hooks portable across machines and collaborators.
Mediumcursorgovernance