Think In Python

Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base

Tue, 31 Mar 2026 02:43:30 +0800

Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base

Abstract: The key to efficiently using Claude Code in large codebases lies in the principle of “Progressive Disclosure.” By building a three-tier hierarchical knowledge base, AI can access just the right amount of context when needed, avoiding token waste and context confusion.

Introduction

As AI-assisted programming tools become ubiquitous, developers face a new challenge: how to use Claude Code effectively in large codebases. Placing a massive README file at the root is far from optimal—it leads to token waste, context confusion, and maintenance difficulties.

This article presents a hierarchical knowledge base best practice, using a three-tier documentation structure to ensure Claude Code receives the right information at the right time.

Core Principle: Progressive Disclosure

Progressive Disclosure means providing high-level rules at the root, then offering increasingly specific “why” and “how” details as AI drills down into subdirectories.

Claude Code natively recognizes CLAUDE.md files. We can extend this pattern into a hierarchical approach, aligning documentation structure with the directory tree.

The 3-Tier Hierarchy

Tier 1: Project Root (Global Context)

File Location: /CLAUDE.md

Purpose: The “Constitution”—defining the tech stack, core commands, and non-negotiable standards.

Example Content:

markdown

## Build Commands
- Production build: `pnpm build`
- Development mode: `pnpm dev`

## Test Commands
- Unit tests: `pnpm test:unit <file>`
- E2E tests: `pnpm test:e2e`

## Code Style
- Functional components only
- No default exports
- Use Tailwind CSS for styling

## Architecture
- Next.js monorepo
- Shared logic in `/packages/shared`

Tier 2: Module/Domain (Strategic Context)

File Location: /src/features/billing/CONTEXT.md

Purpose: Explaining business logic and invisible data flows that code alone won’t reveal.

Example Content:

markdown

## Domain Logic
This module handles Stripe integration.

## Data Flow
All payments must trigger the `webhook-handler` before updating the DB.

## Security
- Never expose Secret_Key to the frontend
- Use the proxy in `/api/stripe` for backend calls

## Dependencies
- Depends on UserStore for tax calculations
- Bidirectional sync with OrderService

Tier 3: Leaf/Component (Tactical Context)

File Location: /src/components/DataGrid/NOTES.md

Purpose: Explaining “gotchas” and specific technical debt.

Example Content:

markdown

## Performance
- Uses react-virtualized for virtual scrolling
- Do not remove the `rowHeight` prop or it will crash on Safari

## Known Issues
- Sorting toggle has a race condition with the API
- Workaround: use `isLoading` ref to debounce

## TODO
- [ ] Extract sorting logic into a standalone Hook
- [ ] Replace deprecated componentWillReceiveProps

Best Practices for “AI-Friendly” Content

1. Be Explicit, Not Idiomatic

❌ Wrong: Just run the tests
✅ Right: Use npm run test

AI models respond better to explicit instructions. Avoid developer “jargon.”

2. Use “Do/Don’t” Lists

AI models respond exceptionally well to negative constraints:

markdown

## Type Safety
- ❌ Don't use 'any' types
- ✅ Use 'unknown' if the type is truly ambiguous
- ✅ Prefer TypeScript strict mode

3. Reference Specific Files

Let AI know where “The Truth” lives:

markdown

## Data Models
- Master schema defined in `/src/db/schema.ts`
- Type exports in `/src/types/index.ts`

4. Keep It Small

Individual context files should be under 50 lines of high-density information. If a file exceeds 10KB, AI may waste too many tokens reading it.

Hierarchical vs. Flat: Comparison

Feature	Flat (One Big README)	Hierarchical (Level-Structured)
Token Usage	High (Claude reads everything every time)	Low (Claude only reads relevant folder’s notes)
Precision	Low (May confuse Webhook rules with UI rules)	High (Specific rules for specific folders)
Maintainability	Hard (One file becomes a “junk drawer”)	Easy (Small files stay close to the code they describe)
Scalability	Poor (Rapidly bloats as project grows)	Good (New modules just add corresponding files)

Implementation Steps

You don’t have to write all of this at once. Adopt a progressive approach:

Phase 1: Root Directory

Create /CLAUDE.md
Define tech stack, build commands, code conventions

Phase 2: Core Modules

Identify 3-5 core business modules
Create CONTEXT.md for each module
Document data flows, security requirements, dependencies

Phase 3: Complex Components

Identify components with technical debt or “gotchas”
Create NOTES.md documenting known issues and workarounds

Phase 4: Let Claude Help

Use Claude Code itself to help generate documentation:

bash

# Ask Claude to analyze a module and generate CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md
 that explains the data flow and security requirements"

Summary

The core value of a hierarchical knowledge base:

Saves tokens: AI reads only relevant context
Improves precision: Specific rules apply to specific scopes
Easy maintenance: Small files stay close to code, low update cost
Scalable: Grows naturally with the project

When starting, begin with /CLAUDE.md at the root, then expand downward. Remember: The value of documentation lies in being used, not in being finished.

References

A Classic KNN Classifier Case — The Iris Flower

Sun, 17 Nov 2019 10:59:31 +0800

Recommended book

This book (Grokking Algorithms) was carefully picked from a large pile of algorithm books. It

focuses on understanding the principles behind algorithms,
replaces obscure formula proofs with vivid examples,
and has genuinely fun illustrations,

which makes it very friendly to non-specialist developers. My own algorithm tutorial series is also built on Grokking Algorithms as its blueprint.

Where to get it

Besides buying the paper edition, you can also find it on WeRead (WeChat Reading), where unlimited reading cards make it a great deal.

Getting started

This post follows chapter 10 of Grokking Algorithms. KNN is one of the entry-level algorithms in machine learning. KNN stands for K Nearest Neighbors, and the principle is very simple: classify by counting the elements nearby in the data’s spatial neighborhood. Our ancestors expressed a similar algorithm in one sentence: birds of a feather flock together.

We will use scikit-learn, which you can install with

shell

pip install scikit-learn

The iris dataset

The iris classification problem is a very classic case for the KNN algorithm. The scikit-learn library ships with a labeled iris dataset: 150 records in total, containing sepal and petal length and width.

After shuffling the data, we split it 3:1 into two groups: one as training data, one as test data. The training data generates the KNN model. Since the computer worked hard to generate a model, we need to evaluate the result and confirm the model actually works — that is where the test data comes in. Run the test data through the model, compare the computed results with the data’s own labels, and you get the model’s accuracy.

One point deserves special attention: both the training and test data are labeled, meaning the flowers were classified by human intelligence. I remember a village in Henan was dubbed an “AI village” — what it actually produces is exactly this kind of labeled data, not real “artificial intelligence” research.

The iris dataset can be loaded with the following code:

python

from sklearn.datasets import load_iris
iris_dataset = load_iris()

Because the iris dataset is ordered, if we split it directly at a 3:1 ratio into:

training data
test data

the distributions would concentrate in specific regions and be uneven. So the data needs to be shuffled before splitting — scikit-learn already provides the tool:

python

from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(
iris_dataset['data'], iris_dataset['target'], random_state=0)

Sharpening the knife

The data is roughly ready. KNN requires the features themselves to be usable as classification conditions for the model to really work — the color of oranges and apples, for example, can serve as a classification feature, while their prices may not. In practice, we should also look at the data first.

python

import pandas as pd
import mglearn

iris_dataframe = pd.DataFrame(X_train, columns=iris_dataset.feature_names)
# color by y_train
grr = pd.plotting.scatter_matrix(iris_dataframe, c=y_train, figsize=(15, 15), marker='o',
hist_kwds={'bins': 20}, s=60, alpha=.8, cmap=mglearn.cm3)

You can clearly see that the existing data basically separates the 3 kinds of flowers, so we can proceed to the next step with confidence.

Cutting the firewood

Now that we have confirmed the data can produce a classifier, it is time to build a model. Thanks to the Python community, we don’t need to build one from scratch — scikit-learn already provides usable classifiers, including the KNN classifier. All we need to do is:

initialize the classifier’s parameters (only a few need to be specified; the rest can stay at their defaults),
train the model,
evaluate and predict.

The K in KNN means how many nearest neighbors — it can be 1, 2, 3, or more. Here we build a model with K = 3, and pass the training data X_train and y_train as parameters to build it.

python

from sklearn.neighbors import KNeighborsClassifier
knn = KNeighborsClassifier(n_neighbors=3)
knn.fit(X_train, y_train)

Note that knn is an object; the fit function actually modifies the internal data of the knn object. The KNN classifier is now ready.

Using the knn.predict method, we can make predictions on data. To evaluate the classifier’s accuracy, we compare the predictions with the test data and compute the hit rate.

python

y_pred = knn.predict(X_test)
print("Test set predictions:\n {}".format(y_pred))
print("Test set score: {:.2f}".format(np.mean(y_pred == y_test)))

In the end, the accuracy reaches 97% — not bad. Your result should be about the same.

From KNN to machine learning

The KNN algorithm is:

very simple in theory,
fast to train (it basically doesn’t learn at all),
relatively accurate,

while at the same time:

computationally heavy (it computes distances between samples and neighboring points),
memory-hungry, because the KNN model relies on the training data itself as parameters,
less accurate for rare categories when samples are imbalanced,
hard to interpret, making it difficult to form explicit rules.

Although KNN is very simple and brute-force, and quite different from today’s popular deep learning, its process of handling data, learning, and predicting — however simple — already contains the basic elements of machine learning.

The code is here: https://github.com/JiangChuanGo/examples/blob/master/KNN/Iris.py

Godlike — The Fourier Transform

Wed, 13 Nov 2019 07:01:04 +0800

Godlike? Not an exaggeration at all!

If we ranked every algorithm, the Fourier transform would absolutely take the crown. How powerful is it?! It basically gave humanity a third eye! It is honestly not something humans should have been able to come up with. Mortals, prepare to worship!

Recommended book

This book (Grokking Algorithms) was carefully picked from a large pile of algorithm books. It

focuses on understanding the principles behind algorithms,
replaces obscure formula proofs with vivid examples,
and has genuinely fun illustrations,

which makes it very friendly to non-specialist developers. My own algorithm tutorial series is also built on Grokking Algorithms as its blueprint.

Where to get it

Besides buying the paper edition, you can also find it on WeRead (WeChat Reading), where unlimited reading cards make it a great deal.

Getting started

This post expands on section 11.3 of Grokking Algorithms. First, let’s meet Fourier: a handsome Frenchman who lived in the 18th century, fought wars alongside Napoleon, served as an official on the imperial payroll, then put down the gun for scholarship — and did rather well at it too, all the way to perpetual secretary of the French Academy of Sciences. A glittering résumé: he followed a big shot, and became one himself.

The principle

I really love drinking cola. The Coca-Cola recipe is supposedly a top secret. It is just sugary water — anyone can easily get a finished bottle — yet nobody can reproduce its taste one hundred percent. This process of analyzing a finished product back into its ingredients is called, in technical terms, reverse engineering. It is usually very hard, because it is an open problem.

Sometimes we are interested not only in the ingredients of food, but also in the ingredients of signals: sound, images. Just like guessing the Coca-Cola formula, figuring out the recipe of a sound or an image is a very difficult piece of reverse engineering. But one man did it: Fourier.

We normally look at signals in the time domain: whatever the signal, we observe it along a progress bar, and that seems to be the only way to look at it. Fourier successfully decomposed a signal into a series of simpler signals — sine waves of different frequencies. That gives us the signal’s recipe: once you know the recipe, you can mix signals of various frequencies together and reproduce the original signal. This recipe is the spectrum. Fourier took humanity’s understanding of signals into the frequency domain.

An interesting property

Follow the same recipe, and shredded pork with garlic sauce tastes roughly the same everywhere. A time-domain signal can be converted to the frequency domain, and converted back, it is still the same signal as before (in practice there are tiny differences, but they don’t matter). If the Fourier transform only gave us the recipe of a signal, that would be a bit underwhelming — on top of it, we can do much more interesting things.

High-pass filtering

Very often we need to extract the edges of an image. How would you do it? Trace them with a pen? Let Papa Fourier take you flying — we use a high-pass filter. This “high-pass” is not the company Qualcomm — it means “letting high frequencies pass”. The edges we see in an image are actually pixels that jump between two different color blocks; if you imagine them as sound, those parts are sharper — in other words, higher in frequency. If we convert an image to the frequency domain, hold back the low-frequency signals, let the high-frequency signals through, and then convert back to the time domain, we get an interesting result.

First, please welcome the image field’s famous model — Ms. Lena.

What does her spectrum look like?

The brighter a region, the more of that frequency component there is. The very center of the spectrum is the low-frequency region; the outer ring is the high-frequency region.

We can see a fairly concentrated blob of information in the low-frequency area. Now we dig out the low-frequency information in the center of the spectrum, and the spectrum looks like this:

Convert the frequency-domain signal back to the time domain, and see what happened to Ms. “Lena”?

We get a “line drawing” — the edges of the image, extracted. All we did was a Fourier transform plus a high-pass filter. Magical, isn’t it!

For audio signals, with the Fourier transform we can easily remove low-frequency noise in the frequency domain, or polish the sound. The principle is roughly the same.

No Fourier, no internet

Today, almost all information is eventually digitized, and digitization uses the Fourier transform and its variants. Only with the Fourier transform can signals be identified as concrete components and digitized.

Next time you use a beauty camera or scroll through short videos, remember to give big boss Fourier a double tap!

The code is here.