代码库正在成为AI的上下文：结构比以往任何时候都重要

AI coding 工具进化得很快。

Claude Code、Cursor、Copilot、Codex 以及其他编码 Agent，现在已经能够检查代码库、编辑多个文件、执行命令、修复 bug，甚至实现完整的功能。

但开发者们开始注意到一个问题：

AI = 上下文的质量

而你的代码库本身，正在成为上下文的一部分。

一个整洁的代码库不再只是帮助你的同事。

它也在帮助 AI 工具理解你在构建什么。

保持代码整洁的旧理由

过去，我们关注代码组织，是因为人类需要理解它。

一个好的项目可能是这样的：

src/
├── features/
│   ├── auth/
│   ├── billing/
│   ├── users/
│   └── notifications/
│
├── components/
├── services/
├── lib/
├── tests/
└── docs/

你能很快理解每样东西在哪里。

现在想象另一个项目：

src/
├── utils.ts
├── utils2.ts
├── helper.ts
├── helper-new.ts
├── service-final.ts
├── service-final-v2.ts
├── old/
├── misc/
└── test123.ts

人类开发者会吃力。

但 AI 编码 Agent 也会吃力。

这就是重要的变化。

你的代码库正在成为 AI Prompt

当你对 AI 编码 Agent 说：

Add subscription cancellation to the application.

这条指令只是 AI 需要信息的极小一部分。

Agent 还需要理解：

• billing 逻辑在哪里
• API 路由在哪里定义
• 使用了哪些数据库模型
• 认证如何工作
• 错误如何处理
• 项目遵循哪些编码规范
• 不应该修改哪些文件

Prompt
   +
Codebase
   +
Documentation
   +
Tests
   +
Naming
   +
Architecture
   =
AI Context

你的整个代码库正在成为 prompt 的一部分。

糟糕的结构产生糟糕的上下文

假设你的应用有支付逻辑分散在十个不相关的文件夹中。

AI Agent 可能会找到：

src/utils/payment.ts
src/helpers/stripe.ts
src/api/payment.js
src/services/payments-new.ts
src/lib/billingHelper.ts

哪个文件是真正的真相来源？

在这个项目工作了两年的开发者可能知道。

AI 大概率不知道。

所以它开始猜测。

问题就出在这里。

• 重复已有逻辑
• 修改了错误的服务
• 创建了另一个不必要的抽象层
• 忽略了已有的 helper
• 引入了不一致的模式

生成的代码可能仍然能运行。

但你的架构变差了。

与其把相关代码散落各处，不如围绕功能来组织它。

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── services/
│   │   ├── hooks/
│   │   └── types.ts
│   │
│   ├── billing/
│   │   ├── components/
│   │   ├── services/
│   │   ├── api/
│   │   └── types.ts
│   │
│   └── users/

现在，当 AI Agent 需要修改 billing 时，上下文是显而易见的。

它知道首先去哪里找。

这减少了不必要的探索，使生成的变更更加可预测。

命名被低估了

开发者有时会低估命名。

看看这些文件：

helper.ts
utils.ts
manager.ts
service2.ts
data.ts

它们几乎什么都没传达。

subscription.service.ts
stripe-webhook.handler.ts
invoice.repository.ts
user-permissions.ts
email-notification.service.ts

第二个版本在任何人打开文件之前就提供了上下文。

这对人类有用。

对 AI 极其有用。

AI 模型严重依赖模式和语义线索。

好的命名给它们更多线索。

文档也有上下文价值

很多仓库的 README 是这样的：

# My App

npm install

npm run dev

技术上说，这是文档。

但它没有解释这个项目。

更好的 README 可能包含：

# Project Architecture

Frontend:
Next.js

Backend:
NestJS

Database:
PostgreSQL

Authentication:
JWT + refresh tokens

Payments:
Stripe

Main feature modules:
- Auth
- Billing
- Projects
- Notifications

然后加上重要的规则：

## Development Rules

- Business logic belongs inside feature services.
- API routes should not contain database queries.
- Shared UI components belong in /components/ui.
- Do not access Stripe directly outside the billing module.

现在你的 README 变成了有用的上下文。

不仅对加入团队的新开发者。

也对你的编码 Agent 有用。

Agent Instructions

越来越多的开发者在维护针对 AI 的仓库级指令。

AGENTS.md

# Agent Instructions

## Architecture

Use feature-based architecture.

## TypeScript

Avoid `any`.

## Database

Use repositories for database access.

## Testing

Every new service should include unit tests.

## Payments

Never modify Stripe webhook logic without updating webhook tests.

## Commands

Run:

npm run lint
npm run test
npm run typecheck

现在 AI Agent 不需要猜测你团队的工作方式了。

你在明确地告诉它。

面向 AI 编码 Agent 的 CONTRIBUTING.md。

测试也是上下文

测试不只是保护你的应用。

它们也解释期望的行为。

想象 AI Agent 找到了这个：

describe("cancelSubscription", () => {
  it("keeps premium access until the billing period ends", async () => {
    ...
  });
});

这一个测试传达了一条重要的业务规则：

取消订阅不应立即移除高级访问权限。

没有这个测试，AI 可能这样实现：

user.plan = "free";

在取消后立即执行。

技术上合理。

业务上完全错误。

好的测试帮助 AI 理解系统应该做什么。

清理死代码

AI Agent 在仓库中搜索。

这意味着旧代码可能成为误导性的上下文。

想象你的仓库包含：

billing/
billing-old/
billing-v2/
stripe-old.ts
stripe-test.ts
stripe-final.ts

人类开发者可能知道哪些是已弃用的。

旧代码制造噪音。

而嘈杂的上下文会产生更差的决策。

因此，删除未使用的代码正变得更有价值。

函数的边界

async function processUser() {
  // authentication
  // billing
  // email
  // analytics
  // permissions
  // database updates
}

authenticateUser()

checkSubscription()

updateUser()

sendNotification()

trackAnalytics()

第二个版本提供了更清晰的边界。

人类和 AI 都能更容易地推理它。

小函数也使自动化变更更安全，因为 Agent 可以只修改一个部分而不触碰其他所有东西。

文档解释"为什么"

有时候代码本身无法解释某样东西存在的原因。

docs/
├── architecture.md
├── authentication.md
├── billing.md
└── deployment.md

你的 billing 文档可能解释了：

Stripe webhooks are the source of truth for subscription state.

Do not update subscription status directly after checkout.

The database is updated only after receiving a verified Stripe webhook.

现在想象问 AI：

Fix subscription state after checkout.

没有文档，Agent 可能直接更新数据库。

有了文档，它理解了这个架构规则。

这个区别很重要。

一致性减少歧义

AI 善于处理模式。

如果你的项目处处使用一种清晰的模式：

controller
→ service
→ repository

Agent 可以轻松遵循它。

但如果每个功能使用不同的架构：

Feature A:
controller → service → repository

Feature B:
route → database

Feature C:
controller → helper → manager → utils → database

AI 就不得不猜测它应该复制哪种风格。

一致性减少了那种歧义。

整洁代码正在成为上下文工程

我们通常认为上下文工程与 prompt、RAG、系统指令或 AI Agent 相关。

但软件开发者应该开始用不同的方式思考它。

你的仓库本身就是上下文。

folder structure
file names
documentation
tests
comments
types
architecture
coding conventions

所有这些都会影响 AI 编码 Agent 理解你的应用的方式。

这意味着整洁架构现在有了另一个好处。

Clean code
→ easier for humans to maintain

Clean code
→ easier for humans to maintain
→ easier for AI to understand
→ better AI-generated changes

开发者工作流正在改变

几年前，开发者主要针对其他开发者优化仓库。

现在我们可能需要针对两个读者优化它们：

Human Developer
      +
AI Coding Agent

这不意味着专门为 AI 创建奇怪的架构。

实际上，结论可能恰恰相反。

AI Agent 理解得最好的东西，往往也是开发者几十年来一直想要的东西：

AI 没有让整洁代码变得不那么重要。

它可能让整洁代码变得比以往任何时候都更重要。

下一代代码库可能不再只从以下角度评判：

"其他开发者能理解这个吗？"

"AI Agent 能在不做出危险假设的情况下理解这个代码库吗？"

因为随着编码 Agent 越来越多地参与真实的开发工作流，你的代码库不再只是代码。

你的代码库是上下文。

更好的上下文通常带来更好的结果。

既然 AI 编码 Agent 正在成为日常开发的一部分，你在代码库里做了哪些不同的实践？