跪拜 Guibai
← Back to the summary

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

This article is the first in the 'Building a Private RAG System from Scratch' series, using Markdown to continuously record project knowledge.

Preface: From 'Loading All Rules' to 'On-Demand Knowledge Retrieval'

In the article '09-Don't Just Put AI in Plan Mode; Give It a Set of Engineering Rules First' from the 'Claude Code Requirement Decomposition in Practice: From Intuition to Deduction (SDD Tutorial)' series, we established an important premise: when using Claude Code to develop a project, you cannot just hand over the current requirements to the AI; you must also let the AI understand the technical and business decisions already formed within the project.

This prevents the AI from guessing project rules from scratch every time. For example:

However, when all these decisions are loaded during Claude Code's cold start, new problems gradually emerge.

Suppose a project has accumulated dozens or even hundreds of rules, but the current task is merely to modify a button style. Loading all the business background, technical choices, and historical solutions at this point causes three obvious issues:

  1. Slower cold starts: The AI needs to read a large volume of documents before it can begin processing the current task;
  2. Increased token consumption: Content unrelated to the task also enters the context;
  3. Dilution of effective information: Truly relevant rules can get lost in a sea of background material.

The problem isn't that we've recorded too much knowledge, but that the method of acquiring knowledge is still 'load everything'.

This series will use RAG (Retrieval-Augmented Generation) to transform this workflow:

User proposes a task
    ↓
Semantically retrieve relevant decisions based on the task
    ↓
Return only the knowledge snippets needed for the current task
    ↓
Claude Code analyzes and implements based on project facts

Engineering rules are still responsible for accumulating knowledge, while RAG is responsible for finding the right knowledge at the right time.

This article won't rush into writing vector retrieval code. Instead, it will first complete the most fundamental input layer for RAG: using Markdown to write technical and business decision documents that are clearly structured, independently understandable, and suitable for subsequent chunking and retrieval.

For an introduction to the tech stack and local development environment setup, please refer to the second article in this series, 'Building a Private RAG System from Scratch: Local Development Environment Preparation'.

1. Why Write Documents First, Instead of Choosing a Vector Database?

The retrieval quality of RAG depends first and foremost on the quality of the original knowledge.

If a document only contains a fragmented conclusion:

The project uniformly uses Solution A.

Then even if this sentence is retrieved, the AI still cannot determine:

A format more suitable for a knowledge base should simultaneously include the decision point, candidate solutions, the final decision, and the reason for the choice:

## FADR #001 - Example Technical Solution

### Feature (Decision Point)
How should the example project solve the target problem?

### Assessment (Evaluation)
Compare the implementation cost, maintenance difficulty, and scope of application of Solution A and Solution B.

### Decision (Decision)
The example project adopts Solution A and limits its usage scope to the specified module.

### Rationale (Reason)
Solution A better fits the current constraints; clearly defining usage boundaries can prevent unnecessary coupling in other modules.

Both pieces of content mention Solution A, but only the latter constitutes a complete, executable, and traceable piece of project knowledge.

Therefore, the first step in building a private RAG knowledge base is not to write all Markdown files into a vector database, but to first ensure that each piece of knowledge can still be understood after being detached from the entire document.

2. What Do Projects Record with BADR and FADR?

CorpRAG divides project decisions into two categories:

Type Full Name Main Content Recorded
BADR Business Architecture Decision Record Business processes, business boundaries, product categories, compliance rules, and other business decisions
FADR Feature Assessment Decision Record Frameworks, state management, component design, network layers, and other technical decisions

Neither is an ordinary project description document.

Ordinary description documents often only describe 'what it is like now,' whereas decision records also explain 'why it became this way' and 'what must not be broken during future modifications.'

1. BADR: Preserving Easily Forgotten Business Reasons

BADR focuses on business issues, such as:

The value of BADR lies in preserving the business reasons behind the code. Code can tell us 'what the system does,' but it usually cannot fully explain 'why the business requires it to be done this way.'

2. FADR: Preserving the Evaluation Process of Technical Choices

FADR focuses on technical issues, such as:

A technical decision cannot just leave behind the final dependency name. Frameworks upgrade, team members change; without recording the candidate solutions and reasons for the choice, subsequent developers can easily redo the selection process without understanding the constraints, or even damage the existing architecture.

3. BADR Business Decision Document Structure Template

BADR and FADR use the same Feature → Assessment → Decision → Rationale structure. The only difference is the type of decision recorded: BADR is for business issues, FADR is for technical issues.

---
title: Project Name Business Architecture Decision Record (BADR)
slug: project-name-badr
date: 2026-07-26
tags: [BADR, Business Architecture]
---

# Business Architecture Decision Record (BADR)

## Project Background

- Project Name:
- Business Type:
- Target Users:
- Core Business Domain:

---

## BADR #001 - Decision Title

### Feature (Decision Point)
What business problem needs to be solved this time?

### Assessment (Evaluation)
| Solution | Advantages | Disadvantages |
| --- | --- | --- |
| Solution A |  |  |
| Solution B |  |  |

### Decision (Decision)
What business solution is ultimately adopted? What clear rules, scope of application, and boundaries must be followed?

### Rationale (Reason)
Why was this solution chosen? Why were other solutions not chosen?

The Role of Each BADR Section

Section Question to Answer
Feature What business problem needs to be solved this time?
Assessment What business solutions were evaluated? What are their respective advantages and disadvantages?
Decision What are the final business rules, scope of application, and boundaries that must be followed?
Rationale Why was this solution chosen over the others?

Not every BADR needs to be very long, but the 'decision point, assessment, decision, reason' should ideally stand on its own.

4. FADR Technical Decision Document Structure Template

A basic FADR uses the Feature → Assessment → Decision → Rationale structure:

---
title: Project Name Technical Decision Record (FADR)
slug: project-name-fadr
date: 2026-07-26
tags: [FADR, Technical Architecture]
---

# Technical Decision Record (FADR)

## Project Background

- Project Type:
- Target Platform:
- Core Constraints:

---

## FADR #001 - Decision Title

### Feature (Decision Point)
What technical problem needs to be solved this time?

### Assessment (Evaluation)
| Solution | Advantages | Disadvantages |
| --- | --- | --- |
| Solution A |  |  |
| Solution B |  |  |

### Decision (Decision)
What solution is ultimately adopted? What clear rules must be followed?

### Rationale (Reason)
Why was this solution chosen? Why were other solutions not chosen?

FADR Case Study: Implementation Location of a Foundational Capability

Below is an example, not tied to any specific framework, illustrating how to record a technical decision:

## FADR #001 - Implementation Location of a Universal Validation Capability

### Feature (Decision Point)
Where should an input validation capability, used by multiple modules, be implemented?

### Assessment (Evaluation)
| Solution | Advantages | Disadvantages |
| --- | --- | --- |
| Implement separately in each module | Flexible to modify, no mutual impact | Rules are easily duplicated and inconsistent |
| Implement uniformly in a shared base layer | Rules are centralized, easy to reuse and test | Requires defining a stable calling interface |

### Decision (Decision)
Universal validation rules are uniformly provided by the shared base layer; module-specific rules remain within their respective modules.

### Rationale (Reason)
Unifying universal rules reduces duplicate implementation, while retaining the independence of module-specific rules prevents the shared layer from taking on too many business responsibilities.

If the AI only reads 'validation capability is implemented uniformly,' it still cannot determine which rules should be shared. A complete FADR simultaneously explains the scope of unification, the boundaries of retention, and the reasons for the choice.

FADR Case Study: Module Communication Boundaries

A technical decision must not only choose a communication method but also clarify usage boundaries:

## FADR #002 - Inter-Module Communication Method

### Feature (Decision Point)
How should modules exchange data and trigger operations?

### Assessment (Evaluation)
| Solution | Advantages | Disadvantages |
| --- | --- | --- |
| Modules directly access each other's internal state | Straightforward implementation | High coupling, internal changes easily affect callers |
| Communicate through public interfaces | Clear boundaries, easy to test | Requires designing interfaces in advance |
| Use a global shared object | Simple to access | Data sources and modification paths are hard to trace |

### Decision (Decision)
Modules communicate only through public interfaces and do not directly access the internal state of other modules.

### Rationale (Reason)
Clear communication boundaries reduce module coupling, allow internal implementations to be adjusted independently, and improve the controllability of testing and maintenance.

This type of record is more valuable than simply writing 'use a certain communication solution,' because what truly impacts code quality is the scope of application and usage boundaries of the solution.

5. What is the Role of the Feature → Assessment → Decision → Rationale Format Template?

The fixed format in Markdown is not to make the document look formal, but to serve developers, retrieval systems, and AI simultaneously.

1. Feature: Defines the Problem Discussed in the Current Segment

Feature defines the decision point in one sentence.

### Feature (Decision Point)
Where should an input validation capability, used by multiple modules, be implemented?

It lets the retrieval system know what question this record answers, and prevents developers from mixing multiple unrelated topics into a single record.

2. Assessment: Preserves Rejected Solutions

Assessment records candidate solutions and their pros and cons.

Recording only the final result loses a lot of background. For example, 'implement validation capability uniformly' does not explain why separate implementation in each module is not allowed. Preserving the evaluation process allows future re-evaluations to judge whether the original limitations still exist, without needing to re-discuss already verified issues.

3. Decision: Forms Executable Project Rules

Decision must be clear, avoiding vague expressions like 'suggest' or 'could consider.'

### Decision (Decision)
Universal validation rules are uniformly provided by the shared base layer; module-specific rules remain within their respective modules.

This part is usually the content the AI most needs to acquire before coding.

4. Rationale: Lets AI Understand the Goal Behind the Rule

Rationale explains the reason for the choice.

When new requirements conflict with old rules, the AI cannot just mechanically repeat the conclusion; it also needs to judge, based on the original goal, whether to continue complying, adjust, or re-evaluate. The rationale is precisely the context needed to make this judgment.

5. Provides Natural Boundaries for Markdown Chunking

Subsequent indexing programs will split long documents into multiple chunks. Stable second and third-level headings can serve as natural boundaries:

## FADR #001 - Implementation Location of a Universal Validation Capability
├── ### Feature
├── ### Assessment
├── ### Decision
└── ### Rationale

The ideal retrieval unit is not a random 500 characters, but a semantically relatively complete decision. A fixed template reduces the probability of two decisions being mixed into the same segment, or a decision and its rationale being completely separated.

6. Improves Recall Probability for Different Phrasings of Questions

Users might ask about the same rule in different ways:

Why isn't each module allowed to implement universal validation separately?
Where are the project's universal validation rules located?
Must module-specific rules also be placed in the shared layer?
How to prevent inconsistent validation rules across multiple modules?

Feature, Assessment, Decision, and Rationale describe the same issue from different angles, providing richer semantic information for the Embedding model, thereby increasing the hit probability for related questions.

7. Makes Retrieval Results Traceable and Reviewable

Each record has a stable type, number, and source. Retrieval results can return:

Conclusion: Modules communicate only through public interfaces.
Source: data/PROJECT-FADR.md
Decision: FADR #002

The AI's answer is no longer just an unverifiable conclusion; developers can trace back to the original text based on the source to review the complete context.

6. Using YAML Frontmatter to Store Document Metadata

In addition to the body structure, the top of each Markdown file can use YAML Frontmatter to describe the document:

---
title: Project Name Technical Decision Record (FADR)
slug: project-name-fadr
date: 2026-07-26
tags: [FADR, Technical Architecture]
---

The body is responsible for storing knowledge for humans to read, while the Frontmatter is responsible for storing metadata for programs to process.

The project can later use gray-matter to parse these fields and convert them into metadata for a LangChain Document:

{
  system: "project",
  docType: "FADR",
  source: "data/PROJECT-FADR.md",
  title: "Project Name Technical Decision Record (FADR)"
}

This metadata is mainly used for:

  1. Filtering: Retrieve only from a specific system or type of decision;
  2. Isolation: Prevent semantically similar but rule-different content from multiple projects from interfering with each other;
  3. Traceability: Return the original file and document title;
  4. Maintenance: Update or rebuild the index for a specified document based on a stable identifier.

It is recommended to save at least the following fields:

Field Purpose
title Describes the document's topic
slug Provides a stable, readable document identifier
date Records the creation or update date
tags Marks the decision type, system, and business domain

7. How to Organize Decision Documents in a Project?

CorpRAG currently organizes Markdown files by 'system + decision type':

data/
├── PROJECT-A-BADR.md
├── PROJECT-A-FADR.md
├── PROJECT-B-BADR.md
├── PROJECT-B-FADR.md
├── PROJECT-C-BADR.md
└── PROJECT-C-FADR.md

Where:

This naming convention allows direct derivation of document metadata:

{
  system: "project-a",
  docType: "BADR",
  source: "data/PROJECT-A-BADR.md"
}

When adding a new system, you can first create:

data/NEW-BADR.md
data/NEW-FADR.md

Then record business and technical decisions separately.

One Decision Solves Only One Core Problem

Don't write state management, routing, request layer, and component specifications all into the same FADR. Too many topics reduce retrieval precision and are not conducive to independent updates later.

Keep Stable Numbers in Titles

## FADR #003 - Mobile Adaptation Solution

Stable numbers facilitate citation, retrieval, review, and tracking. Titles can be adjusted, but numbers should not be reused casually.

Don't Just Copy Code

Code examples can serve as evidence but cannot replace decision explanations. Code changes, while decision records need to explain constraints and goals.

Record the Scope of Application of Rules

The same rule might only apply to a specific system, product line, or channel. A lack of scope description can cause the AI to mistake a local solution for a company-wide unified standard.

8. How to Self-Check After Writing a Decision?

Before putting a decision into the knowledge base, you can use the following checklist:

Content Check

Retrieval Check

Maintenance Check

9. What Was Accomplished in This Chapter?

This chapter completed the input layer preparation for a private RAG knowledge base:

  1. Identified the speed and token problems caused by cold-start loading of all engineering rules;
  2. Decided to use RAG to retrieve relevant decisions based on task semantics;
  3. Used BADR to record business background, business rules, and constraints;
  4. Used FADR to record technical solution evaluations, decisions, and reasons;
  5. Explained the role of the Feature → Assessment → Decision → Rationale template for reading, chunking, retrieval, and traceability;
  6. Used YAML Frontmatter to store document metadata;
  7. Established standards for writing and self-checking decision documents.

We aim to gradually transform Claude Code's knowledge acquisition method from:

Every startup
  ↓
Load all technical and business decisions
  ↓
Start processing tasks

To:

Receive task
  ↓
Retrieve relevant decisions
  ↓
Load only necessary context
  ↓
Complete task based on project facts

Summary

A usable private RAG knowledge base doesn't start with a vector database, but with seriously recording the first project decision.

BADR preserves the reasons and boundaries behind business rules, and FADR preserves the evaluation process and usage constraints of technical solutions. A fixed Markdown structure gives each decision relatively complete semantics, while YAML Frontmatter allows programs to identify, filter, and trace documents.

RAG won't create project knowledge for us. It solves the problem of:

When knowledge grows, instead of stuffing all content into the AI's context, only find the part truly needed for the current task.

Before continuing, please read the second article in this series, 'Building a Private RAG System from Scratch: Local Development Environment Preparation,' to understand the tech stack and configure the development environment.

Once the environment is ready, we will start with Markdown document loading and text chunking, gradually implementing the indexing pipeline for CorpRAG.