第 12 章：Project Knowledge：README、CLAUDE.md 与 AGENTS.md

本章导读

• 核心问题：如何让 Agent 理解一个具体项目的构建命令、规则和常见坑。
• 关键词：Project Knowledge、README、AGENTS.md、RepositoryProfile、ProjectKnowledgeLoader
• 学习产出：为 order-service 设计能指导 CI 排障的 AGENTS.md。

1. 本章要解决什么问题

前一章讨论了 Skill。

这一章讨论一种特殊但非常重要的 Skill-like 资源：Project Knowledge。

对 Coding Agent 来说，项目本身不是一堆文件，而是一个有规范、有历史、有构建方式、有测试方式、有团队约定的软件系统。

人类工程师加入一个项目时，会先读：

README.md
开发环境文档
测试说明
架构说明
代码规范
常见问题
PR 规范

Agent 也需要这些内容。

如果没有 Project Knowledge，Agent 可能会：

• 不知道如何运行测试；
• 不知道项目使用 Maven 还是 Gradle；
• 不知道哪些目录不能改；
• 不知道团队代码风格；
• 不知道常见坑；
• 重复探索显而易见的信息；
• 运行错误命令；
• 生成不符合项目风格的代码。

本章核心观点是：

Project Knowledge 是 Agent 理解代码库的入口上下文，也是把团队工程约定显式化的机制。

本章回答：

• README、CLAUDE.md、AGENTS.md 各自适合放什么；
• 什么内容应该写给 Agent，什么内容不应该写；
• 项目知识如何进入 Context Layer；
• 如何避免项目知识变成长而无用的文档；
• 如何在 Java / Spring Boot 平台中实现 ProjectKnowledgeLoader。

2. 对应 Anthropic 文章

本章主要对应：

• Claude Code: Best practices for agentic coding
• Equipping agents for the real world with Agent Skills

Claude Code 最佳实践中强调，项目级指令文件应该包含 Claude 无法轻易猜到的信息，例如：

• Bash 命令；
• 测试指令；
• 特殊代码风格；
• Git 工作流；
• 环境变量；
• 常见坑。

同时也不应该包含：

• 模型可以自己通过读代码发现的内容；
• 标准语言规范；
• 冗长 API 文档；
• 经常变化的信息；
• 空泛要求。

这对企业研发 Agent 很重要。

3. Project Knowledge 的组成

3.1 README.md：项目入口

README 面向人，也面向 Agent。

它应该回答：

这个项目是什么？
核心模块是什么？
如何启动？
如何构建？
如何测试？
如何贡献？

README 更像项目概览，不应承载太多 Agent 专用规则。

3.2 AGENTS.md / CLAUDE.md：Agent 操作手册

AGENTS.md 或 CLAUDE.md 面向 Coding Agent。

它应该回答：

Agent 在这个项目中应该如何工作？
哪些命令应该使用？
哪些操作禁止？
修改后如何验证？
团队有哪些非显而易见规则？

建议采用 AGENTS.md 作为通用命名，因为它不绑定特定模型或厂商。

CLAUDE.md 可以作为 Claude Code 的特定入口。

在企业平台中，可以同时支持：

AGENTS.md
CLAUDE.md
.agent/instructions.md

并按优先级合并。

3.3 构建文件

构建文件也是 Project Knowledge：

pom.xml
build.gradle
package.json
Makefile
Dockerfile
compose.yml

Agent 可以从中推断：

• 技术栈；
• 依赖；
• 测试框架；
• 构建命令；
• 插件；
• Java 版本；
• 模块结构。

但构建文件通常较长，需要提取摘要。

3.4 目录结构

目录结构帮助 Agent 快速定位：

src/main/java
src/test/java
src/main/resources
docs
scripts
infra

不要把每个文件都解释一遍。

只需要提供模块级导航。

3.5 项目规范

项目规范可以包括：

• 编码规范；
• 测试规范；
• 分支规范；
• PR 规范；
• 日志规范；
• 异常处理规范；
• API 兼容性要求。

这些信息对 Agent 非常有价值。

3.6 常见坑

常见坑是最适合写给 Agent 的内容。

例如：

不要直接修改 OrderStatus 枚举，必须同步更新 OrderStateMachine。
新增 Controller 时必须补充 OpenAPI 注解。
测试中不要连接真实 Redis，使用 EmbeddedRedisTestConfig。

这些是模型无法从通用知识中推断出来的项目经验。

4. AGENTS.md 应该写什么

一个好的 AGENTS.md 应该短、具体、可执行。

推荐结构：

# AGENTS.md

## Project Overview

## Build and Test Commands

## Coding Rules

## Testing Rules

## Safety Rules

## Common Gotchas

## Output Requirements

4.1 Build and Test Commands

应该写明确命令：

- Run all tests: `./mvnw test`
- Run one test class: `./mvnw -Dtest=ClassName test`
- Run checkstyle: `./mvnw checkstyle:check`

不要写：

运行适当的测试。

4.2 Coding Rules

写项目特有规则：

- Use constructor injection; field injection is not allowed.
- Keep controllers thin; business logic belongs in service classes.
- Do not introduce new dependencies without approval.

不要写标准常识：

- Write clean code.
- Avoid bugs.

4.3 Testing Rules

例如：

- Service layer changes require unit tests.
- Repository changes require integration tests.
- Do not use external network calls in tests.
- Reuse fixtures under `src/test/java/.../fixtures`.

4.4 Safety Rules

例如：

- Do not modify migration files unless explicitly requested.
- Do not run destructive shell commands.
- Ask before changing public API contracts.
- Never read or print secrets from `.env` files.

4.5 Common Gotchas

例如：

- Order state transitions are centralized in `OrderStateMachine`.
- Changing `OrderStatus` requires updating tests in `OrderServiceTest`.
- Local tests use H2; CI uses PostgreSQL.

5. AGENTS.md 不应该写什么

5.1 不写模型能自己发现的信息

例如每个文件的功能说明。

Agent 可以通过搜索和读取文件自己发现。

5.2 不写过长教程

AGENTS.md 不是技术教程。

长文档应放到 docs，然后在 AGENTS.md 中引用。

5.3 不写频繁变化的信息

例如临时版本号、某个短期分支说明。

这些容易过期并误导 Agent。

5.4 不写敏感信息

不要包含：

• 密钥；
• token；
• 生产密码；
• 私有客户数据；
• 内部漏洞细节。

5.5 不写空泛口号

例如：

请认真工作
请保证质量
请遵循最佳实践

这些没有可执行性。

6. Project Knowledge 的加载策略

Project Knowledge 也要遵循 Context Engineering。

不要每次都全量加载。

推荐策略：

启动任务时加载项目摘要和 AGENTS.md 核心规则
按任务类型加载相关文档
按需要读取构建文件和目录结构
长文档只保留引用和摘要

例如：

• 编码任务：加载 AGENTS.md、构建命令、相关代码规范；
• 测试任务：加载测试规则、相似测试、fixture 说明；
• 部署任务：加载部署文档、安全规则；
• API 文档任务：加载 OpenAPI 规范和接口风格。

7. 架构图 / 流程图

7.1 Project Knowledge 来源

7.2 Project Knowledge 注入

7.3 AGENTS.md 维护闭环

8. Java / Spring Boot 落地方案

8.1 RepositoryProfile

public record RepositoryProfile(
    String repositoryId,
    String name,
    String summary,
    TechStack techStack,
    List<String> buildCommands,
    List<String> testCommands,
    List<String> codingRules,
    List<String> testingRules,
    List<String> safetyRules,
    List<String> commonGotchas,
    List<ProjectDocumentRef> documents
) {}

8.2 ProjectKnowledgeLoader

public interface ProjectKnowledgeLoader {
    RepositoryProfile load(String repositoryPath);
}

8.3 AgentInstructionFileParser

public interface AgentInstructionFileParser {
    boolean supports(Path path);
    AgentInstruction parse(Path path);
}

支持：

AGENTS.md
CLAUDE.md
.agent/instructions.md

8.4 BuildCommandResolver

public interface BuildCommandResolver {
    List<String> resolveBuildCommands(Path repositoryPath);
    List<String> resolveTestCommands(Path repositoryPath);
}

可以根据文件判断：

pom.xml → ./mvnw test 或 mvn test
build.gradle → ./gradlew test
def package.json → npm test

8.5 ProjectKnowledgeContextProvider

@Component
public class ProjectKnowledgeContextProvider implements ContextProvider {

    private final ProjectKnowledgeLoader loader;

    @Override
    public boolean supports(ContextRequest request) {
        return request.repositoryId() != null;
    }

    @Override
    public List<ContextChunk> provide(ContextRequest request) {
        RepositoryProfile profile = loader.load(request.repositoryPath());
        return List.of(toContextChunk(profile));
    }
}

9. 示例：Spring Boot 项目的 AGENTS.md

# AGENTS.md

## Project Overview

This is a Spring Boot service for order management.

## Build and Test Commands

- Run all tests: `./mvnw test`
- Run one test class: `./mvnw -Dtest=ClassName test`
- Run checkstyle: `./mvnw checkstyle:check`

## Coding Rules

- Use constructor injection, not field injection.
- Keep controller logic thin; business logic belongs in service classes.
- Do not introduce new dependencies without approval.
- Public API changes require explicit user confirmation.

## Testing Rules

- Add unit tests for service-layer changes.
- Add integration tests for repository changes.
- Reuse test fixtures under `src/test/java/.../fixtures`.
- Do not call external network services in tests.

## Safety Rules

- Do not modify database migration files unless explicitly requested.
- Do not run destructive commands such as `rm -rf`.
- Never read or print secrets from `.env` files.

## Common Gotchas

- Order status transitions are centralized in `OrderStateMachine`.
- Changing `OrderStatus` requires updating `OrderServiceTest`.
- CI runs on PostgreSQL even though local tests may use H2.

## Output Requirements

When finishing a coding task, report:

- changed files;
- commands run;
- test results;
- known risks.

10. 常见误区

10.1 把 AGENTS.md 写成项目百科

AGENTS.md 应是操作手册，不是完整文档库。

10.2 不维护项目知识

过期命令比没有命令更危险。

10.3 把敏感信息写进去

Agent 指令文件可能被模型读取，不能包含密钥。

10.4 规则过于空泛

规则必须具体、可执行、可验证。

10.5 只给人看，不给 Agent 优化

AGENTS.md 应根据 Agent 失败案例不断改进。

11. 贯穿案例：CI 失败分析 Agent

在 order-service 项目中，AGENTS.md 对 CI 失败分析非常关键。

它可以告诉 Agent：

## Build and Test Commands
- Run all tests: `./mvnw test`
- Run one test class: `./mvnw -Dtest=ClassName test`

## Common Gotchas
- Order status transitions are centralized in `OrderStateMachine`.
- Changing `OrderStatus` requires updating `OrderStateMachine` and `OrderServiceTest`.
- CI uses PostgreSQL even though some local tests use H2.

当 build #4312 失败时，Agent 看到 OrderStatus 新增 PENDING_REVIEW，再结合 AGENTS.md 中的项目规则，就能更快定位状态机未更新这一类问题。

这说明 Project Knowledge 不是普通文档，而是 Agent 的项目操作手册。

没有 AGENTS.md，Agent 可能需要多轮搜索才能发现状态流转规则；有了 AGENTS.md，它可以更快形成高质量假设并用代码证据验证。

12. 本章小结

本章讨论了 Project Knowledge。

核心结论：

1. Project Knowledge 是 Coding Agent 理解项目的入口。
2. README 适合项目概览，AGENTS.md / CLAUDE.md 适合 Agent 操作指令。
3. 好的 Agent 指令文件应短小、具体、可执行。
4. 项目知识也需要选择、压缩和权限治理。
5. AGENTS.md 应像代码一样进入版本控制和评审。

一句话总结：

项目知识文件不是文档装饰，而是让 Agent 遵守团队工程约定的接口。

13. 实践任务

任务 1：为项目编写 AGENTS.md

选择一个真实项目，写一个不超过 100 行的 AGENTS.md。

任务 2：实现 ProjectKnowledgeLoader

实现读取 README、AGENTS.md、pom.xml 的 Loader，输出 RepositoryProfile。

任务 3：项目知识审查

检查你的 AGENTS.md：

• 是否有过期命令；
• 是否有空泛规则；
• 是否包含敏感信息；
• 是否过长；
• 是否缺少测试命令。

任务 4：从失败中更新规则

记录一次 Agent 犯错案例，判断是否需要更新 AGENTS.md、Tool 描述、Skill 还是 Context Selection 策略。