101 lines
6.7 KiB
Markdown
101 lines
6.7 KiB
Markdown
---
|
||
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
|