Frontend · Backend · AI Programming

Stop Dumping Your Entire Codebase into AI Context: Write Decisions It Can Actually Retrieve

By 颜进强 · Jul 26, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams adopting AI coding agents quickly hit a ceiling where context windows overflow with stale rules. A retrieval step that depends on well-structured source documents cuts token waste and lets agents justify answers with traceable references, which is the difference between a demo and a workflow you can audit.

Summary

Feeding every project rule to an AI agent on cold start burns tokens and buries relevant context. The fix is a retrieval-augmented generation pipeline that pulls only the decisions a task actually needs. But retrieval quality collapses if the underlying documents are just scattered conclusions. Two lightweight templates—BADR for business rules and FADR for technical choices—use a fixed Feature → Assessment → Decision → Rationale structure that makes each record independently understandable, naturally chunkable, and semantically dense enough for embedding models to match against varied queries. YAML frontmatter supplies machine-readable metadata for filtering, isolation, and traceability, so an agent can cite the exact source file and decision number instead of emitting an unverifiable claim. The directory convention is deliberately flat: one file per system per decision type, keeping the ingestion pipeline simple before any vector database enters the picture.

Takeaways

— Cold-start loading of all project rules into an AI agent slows response, wastes tokens, and dilutes the signal of relevant constraints.

— RAG retrieval quality is determined by source-document structure before any vector database is chosen.

— BADR (Business Architecture Decision Records) capture business rules, boundaries, and the reasons behind them that code alone cannot express.

— FADR (Feature Assessment Decision Records) capture technical choices, evaluated alternatives, and explicit usage boundaries.

— The Feature → Assessment → Decision → Rationale template ensures each record is semantically complete even after chunking, improving embedding match rates.

— YAML frontmatter provides machine-readable metadata for filtering by system or decision type, isolating projects, and enabling traceable citations.

— A flat directory of `SYSTEM-BADR.md` and `SYSTEM-FADR.md` files keeps the ingestion pipeline simple and metadata derivable from filenames.

— A self-check checklist verifies that a decision is independently understandable, keyword-rich, and scoped with explicit boundaries and exceptions.

Conclusions

Most RAG advice jumps straight to vector databases and chunking strategies, but the real bottleneck is upstream: documents written as narrative prose produce garbage retrieval units no matter how good the embedding model is.

The BADR/FADR split mirrors a split that Western ADR (Architecture Decision Records) culture often neglects—business rules decay differently than technical ones and deserve their own lifecycle and retrieval path.

Requiring a stable decision number and source path in every retrieval result turns an AI agent from an oracle into an auditable tool, which matters more for compliance-heavy teams than any benchmark score.

The template's four sections act as a cheap semantic expansion trick: the same decision expressed four ways increases the chance an embedding model will match it against a user's rephrased question.

Concepts & terms

RAG (Retrieval-Augmented Generation)

A pattern that retrieves relevant documents or snippets from a knowledge base and injects them into an LLM's prompt, so the model grounds its answer in provided facts rather than relying solely on training data.

BADR (Business Architecture Decision Record)

A structured Markdown record capturing a business decision, its evaluated alternatives, the final rule, and the business rationale—preserving context that source code cannot express.

FADR (Feature Assessment Decision Record)

A structured Markdown record capturing a technical decision, candidate solutions with trade-offs, the chosen approach with explicit usage boundaries, and the reasoning behind the choice.

YAML Frontmatter

A block of YAML key-value pairs at the top of a Markdown file, delimited by `---`, used to store machine-readable metadata like title, slug, date, and tags for programmatic filtering and indexing.

Chunking

The process of splitting a long document into smaller, semantically coherent segments before embedding and indexing, so retrieval can return precise snippets rather than entire files.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗