AI Coding Conventions Organization — External Research Synthesis

Research findings on how practitioners organize opinionated coding conventions and standards to guide AI coding assistants (Claude, Cursor, Copilot, etc.) toward consistently high-quality output. Gathered during a session exploring improvements to this workspace's OO principles conventions.

Core Finding

Reference documentation with code examples outperforms process flowcharts for AI coding behavior. LLMs already know the concepts — what they need is project-specific patterns, failure modes, and examples. However, process does matter at the routing layer: trigger tables and decision gates in a "constitution" document tell the AI what context to load and when.

The Three-Tier Architecture (Codified Context, arXiv 2602.20478)

The most empirically rigorous approach, documented across 283 sessions on a 108,000-line C# codebase. Context infrastructure totaled 24.2% of codebase size — treated as load-bearing infrastructure.

Tier 1 — Constitution (~660 lines, always loaded) Coding conventions, naming rules, build commands, architectural summaries, orchestration protocols, and trigger tables that route tasks to domain specialists. Must stay concise; details live downstream.

Tier 2 — Domain Specialist Agents (300–700 lines each, on-demand) Over half the content of each agent is project-domain knowledge (patterns, formulas, known failure modes), not behavioral instructions. Invoked by trigger table based on which files are being modified.

Tier 3 — Knowledge Base (on-demand, served via MCP) Deep specification documents (~16k lines total), formatted for machine consumption.

Quantitative result: 2,801 human prompts generated 16,522 autonomous agent turns.

Token Efficiency Strategies

Keep always-loaded context small — under 200 lines for root files. Frontier models follow ~150–200 instructions before compliance degrades. Claude's own system prompt consumes ~50 slots.
Just-in-time retrieval — maintain lightweight identifiers (paths, doc titles) and load content only when needed
Linters/formatters replace style rules — if a tool can enforce it deterministically, don't document it
Automated backpressure — instruct agent to run lint:fix/typecheck after changes; the output IS the feedback loop
Examples over enumeration — one canonical worked example outperforms exhaustive lists of minimal-variation cases
Positive framing only — negative instructions prime the model toward the forbidden pattern

Organizational Patterns

Root file (CLAUDE.md, .cursorrules, AGENTS.md): Always loaded, under 200–300 lines. Technology stack, essential commands, domain terminology, pointers to deeper docs, non-negotiable guardrails.

Hierarchical scoping (AGENTS.md / Cursor .mdc): Nested files override parents. Subproject-level instructions without polluting global context. The AGENTS.md spec: "The closest AGENTS.md to the edited file wins." OpenAI's main repo carries 88 AGENTS.md files.

Cursor rule types:

alwaysApply: true — loaded every session
Auto-attached — loaded when matching glob patterns are opened
Agent-requested — agent self-selects based on description
Manual (@ruleName) — developer explicitly invokes

Feedback loop documentation (the /learn pattern): Mistakes → conversation analysis → persistent docs → auto-loaded next session. Converts errors into permanent constraints without model retraining.

Process vs. Reference Design

Process encoding works best as trigger tables in the constitution (what context to load when), not as step-by-step workflows in content documents
Reference docs with examples are what specialist agents and knowledge base contain
Decision trees / flowcharts work when framed as routing logic at the constitution layer, not as concept documentation

Context Linking Patterns

Root file as map; deeper docs as territory (file path references)
Trigger tables: modified files in X domain → consult specialist agent Y
IMPORTANT directive pattern: "Before starting any task, identify which documentation is relevant and read it first"
Hierarchical override: subproject files override workspace-level files

Enforcement Mechanisms (strongest to weakest)

Automated tools (linters, formatters, type checkers) — deterministic
Scoped loading (auto-attach only relevant context) — structural
Trigger tables in constitution — routing enforcement
Feedback loop documentation — accumulated institutional memory
Instruction placement (priority directives at top of always-loaded files)
Conciseness — shorter instruction sets are better enforced; exceeding 150–200 instructions causes unpredictable selective ignoring

Key Tradeoffs

Comprehensiveness vs. compliance: More instructions degrade compliance beyond ~200. Solution: move detailed instructions to on-demand layers, not always-loaded context.

Specificity vs. generality: "Write idiomatic code" is useless; "Use stem not slug in Nuxt Content queries" is actionable. Over-specification creates rigidity.

Process vs. flexibility: Rigid workflows reduce variance for routine tasks but fail on edge cases. Trigger tables for routing + flexibility within domains is the balance.

Documentation overhead vs. velocity: High upfront cost, compounds over time. Only worthwhile for large, long-horizon projects.

Single file vs. distributed system: Simple to maintain vs. more powerful but fragile. Don't adopt distributed context until single-file demonstrably falls short. "Agents trust documentation absolutely" — a wrong spec produces confidently incorrect code.

Notable Public References

Codified Context paper: arxiv.org/abs/2602.20478 — most rigorous empirical treatment
github.com/arisvas4/codified-context-infrastructure — companion templates and examples
Anthropic Effective Context Engineering: anthropic.com/engineering/effective-context-engineering-for-ai-agents
PatrickJS/awesome-cursorrules — large collection of real-world examples
alexop.dev — Stop Bloating Your CLAUDE.md — practical progressive disclosure implementation
mbleigh.dev — Rules for Rules — writing docs for LLMs
agents.md — AGENTS.md open standard

6.7 KiB Raw Permalink Blame History Unescape Escape