SecondBrain/2026-03-13-ai-coding-conventions-organization-external-research-synthesis.md

---
source: "hyperthrive_dev"
date: "2026-03-13"
tags: [research, ai-conventions, context-engineering, claude-md, progressive-disclosure, token-efficiency, cursor-rules, codified-context, three-tier-architecture]
---

# 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)

1. Automated tools (linters, formatters, type checkers) — deterministic
2. Scoped loading (auto-attach only relevant context) — structural
3. Trigger tables in constitution — routing enforcement
4. Feedback loop documentation — accumulated institutional memory
5. Instruction placement (priority directives at top of always-loaded files)
6. 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

## See Also

- [[99 Bottles OOP — Full Software Design Process Map]] — the OO design lifecycle this workspace is encoding
- [[OO Principles Plugin Concept — Design Recommendations]] — how to apply these findings to a plugin