1. 项目概述：一个为Claude设计的代码知识库
最近在跟一些做AI应用开发的朋友聊天，大家普遍有个痛点：虽然像Claude这样的AI助手在代码理解和生成上已经很强了，但面对一些复杂的、特定领域的项目时，它给出的建议往往还是不够“地道”。要么是代码风格不统一，要么是忽略了项目特有的最佳实践。这让我想起自己之前折腾的一个小项目——huifer/claude-code-book，本质上，它是一个专门为Claude“喂养”的代码知识库。
你可以把它理解为一本高度定制化的“代码食谱”或者“项目规范手册”。它的核心目标不是直接运行某个程序，而是通过整理、归纳一个特定项目（比如一个开源框架、一个公司内部的核心库）的代码结构、命名规范、设计模式、常见问题及解决方案，形成一个结构化的知识集合。然后，你可以把这些知识“教”给Claude，让它在这个项目的语境下，提供更精准、更符合项目习惯的代码建议、重构方案甚至是bug排查思路。
这个想法源于一个很实际的需求。假设你接手了一个庞大的遗留系统，或者你们团队维护着一个有自己独特编码哲学的开源项目。新成员上手需要时间，即使是经验丰富的开发者，在写一些边缘模块时也可能偏离既定规范。而claude-code-book试图解决的，就是让AI助手成为这个项目的“活字典”和“资深顾问”，它能基于你提供的知识，给出仿佛是这个项目核心贡献者写出的代码。
2. 核心设计思路：如何为AI构建“领域知识”
2.1 从“通用编程”到“领域专家”的转变
通用的大型语言模型（LLM）如Claude，是在海量的公开代码和文本上训练的。这赋予了它强大的通用编程能力，但它缺乏对任何一个特定代码库的“深度记忆”和“上下文理解”。它不知道你的项目里utils文件夹下有个神奇的formatData函数处理了所有边界情况，也不清楚你们团队约定俗成地用_internal前缀表示私有模块。
huifer/claude-code-book的设计思路，就是主动为Claude构建这份“领域知识”。它不是简单地把整个代码库扔给AI（那会超出上下文窗口，且信息杂乱），而是进行了一次精心的“知识蒸馏”。这个过程包括：
- 知识提取：从目标代码库中，提取出关键的结构信息（如目录树、核心模块的依赖关系）、代码模式（如常用的函数签名、类的继承体系）、文档片段（如README、核心接口的注释）。
- 知识结构化：将提取出的信息，按照人类和AI都易于理解的方式组织起来。例如，用Markdown文件描述项目的整体架构，用JSON或YAML列出重要的配置项和其含义，用代码片段示例展示特定功能的标准写法。
- 知识注入：在与Claude对话时，将这些结构化的知识作为系统提示（System Prompt）或上下文的一部分提供给AI。这样，Claude在回答问题时，就能优先参考这本“代码书”里的内容。
2.2 知识库的构成要素
一个有效的claude-code-book通常包含以下几个层次的内容，这决定了AI能学到多深：
- 架构层描述：用文字和图表（如文本化的Mermaid语法描述，虽然我们输出不用，但可以准备）说明项目的核心模块、数据流、技术选型背后的原因。例如：“本项目采用分层架构，Web层使用Express，服务层处理业务逻辑，数据访问层封装了Sequelize ORM。特别注意，所有数据库查询必须通过数据访问层提供的
BaseRepository进行，禁止直接写原生SQL。” - 代码规范与模式：这是最实用的部分。列出命名规范（如“接口以
I开头，抽象类以Abstract开头”）、函数/方法的推荐写法、错误处理的统一方式（如“所有异步操作必须用try-catch包裹，并使用AppError自定义错误类抛出”）。最好附上正反例对比的代码片段。 - 核心算法与逻辑摘要：对于项目中复杂的核心算法或业务逻辑，用伪代码或精简后的代码配合详细注释进行说明。帮助AI理解“为什么这么做”，而不仅仅是“做了什么”。
- 常见“坑”与解决方案：记录项目历史中常见的bug、性能瓶颈及其修复方案。例如：“在
userService.update方法中，曾因未检查乐观锁版本号导致数据覆盖，现规范写法必须传入version字段。”这能直接提升AI在问题诊断上的能力。 - 外部依赖与配置说明：清晰说明项目依赖的关键第三方库的版本、特殊配置，以及为何选择它们。比如：“使用
lodash的get函数进行深层属性访问，以替代可选的链式操作符，确保在Node.js 12环境下的兼容性。”
注意：构建知识库时，切忌变成简单的代码堆砌。重点在于提炼“规则”、“意图”和“上下文”，而不是提供每一行代码。AI需要的是指导原则，而不是完整的复制品。
3. 实操构建：一步步创建你的Claude代码书
3.1 环境与工具准备
你不需要复杂的开发环境。本质上，claude-code-book就是一个精心组织的文档集合。推荐的工具链非常简单：
- 代码仓库：直接在GitHub、GitLab或Gitee上新建一个仓库，命名为
your-project-code-book。这是知识库的载体，也方便版本管理和团队协作。 - 文档工具：Markdown是你的最佳选择。它轻量、易读，且被Claude完美支持。你可以使用任何你喜欢的Markdown编辑器，如VS Code（配合Markdown插件）、Typora或Obsidian。
- 代码分析辅助工具（可选但推荐）：
tree命令：快速生成项目的目录结构树状图。grep/ripgrep：用于搜索特定的代码模式或关键字。- AST（抽象语法树）分析工具：对于大型项目，可以使用像
pyastgrep（Python）或jscodeshift（JavaScript）这样的工具，以编程方式提取代码结构信息，但这属于进阶用法。
3.2 知识提取与文档化流程
假设我们要为一个名为ShopAPI的虚构电商后端项目构建代码书。
第一步：搭建文档骨架在仓库根目录创建以下基本结构：
/shopapi-code-book ├── README.md # 知识库总览和使用说明 ├── ARCHITECTURE.md # 系统架构详解 ├── CODING_STANDARDS.md # 编码规范 ├── CORE_MODULES/ # 核心模块详解目录 │ ├── user_service.md │ ├── order_service.md │ └── payment_gateway.md ├── COMMON_PITFALLS.md # 常见问题与解决方案 └── snippets/ # 存放示例代码片段 ├── good_practice.js └── bad_practice.js第二步：填充架构信息（ARCHITECTURE.md）不要只贴架构图。用文字描述清楚：
## 1. 整体架构 ShopAPI 采用基于领域驱动设计（DDD）思想的模块化架构。主要分为： - **API层**：`/routes/*`，使用Express.js框架，负责接收HTTP请求、参数校验和返回响应。**所有路由控制器必须保持精简，仅做流程编排，业务逻辑下沉至服务层。** - **应用服务层**：`/services/*`，核心业务逻辑所在地。每个服务对应一个主要的领域聚合根（如OrderService, UserService）。**服务之间通过接口调用，禁止直接依赖数据库模型。** - **领域层**：`/domains/*`，包含实体（Entity）、值对象（Value Object）和领域服务。**实体类包含业务规则验证，其状态变更必须通过定义的方法进行。** - **基础设施层**：`/infra/*`，包含数据库模型（Sequelize）、外部API客户端、消息队列生产者/消费者等。**该层依赖抽象（接口），以便于测试和替换。** ## 2. 数据流 典型创建订单流程： 1. 请求到达 `POST /api/orders` -> `OrderController.create` 2. 控制器调用 `OrderService.createOrder(payload, userId)` 3. `OrderService` 内部： - 通过 `UserRepository` 验证用户状态 - 通过 `ProductRepository` 锁定库存（使用事务） - 创建 `Order` 和 `OrderItem` 领域实体 - 调用 `PaymentService` 处理支付 - 通过 `OrderRepository` 持久化实体 - 发布 `OrderCreatedEvent` 到消息队列 4. 控制器返回创建结果。第三步：定义编码规范（CODING_STANDARDS.md）具体、可执行，避免“代码要清晰”这样的模糊描述。
## 1. 命名规范 - **文件与目录**：使用小写蛇形命名法（snake_case）。例如：`user_repository.js`, `order_service.js`。 - **类与构造函数**：使用帕斯卡命名法（PascalCase）。例如：`class UserRepository`, `function AppError()`。 - **变量与函数**：使用驼峰命名法（camelCase）。**布尔变量以`is`， `has`， `can`开头**。例如：`const isValidUser = true;`, `async function calculateTotalPrice() {}`。 - **常量**：使用大写蛇形命名法（UPPER_SNAKE_CASE）。例如：`const MAX_RETRY_TIMES = 3;`。 ## 2. 异步处理 - **统一使用`async/await`**，禁止使用回调函数（Callback）处理核心逻辑。 - **错误处理**：所有`await`调用必须用`try-catch`包裹。在Service层，抛出统一的`AppError`或其子类。 ```javascript // 正确示例 try { const user = await userRepository.findById(userId); if (!user) { throw new NotFoundError('User not found'); } // ... 业务逻辑 } catch (error) { // 记录日志，或向上抛出 throw error; // 或转换为AppError } // 错误示例：缺少错误处理 const user = await userRepository.findById(userId);**第四步：详解核心模块（CORE_MODULES/user_service.md）** 深入到具体模块，解释其职责、关键方法和注意事项。 ```markdown ## UserService 用户服务 **职责**：管理用户生命周期，包括注册、登录、信息更新、权限验证。 ### 关键方法 1. `register(email, password, profile)` - **逻辑**：检查邮箱唯一性 -> 密码加盐哈希（使用`bcrypt`） -> 创建用户记录 -> 发送欢迎邮件（异步）。 - **注意**：密码哈希操作是CPU密集型，必须异步执行，避免阻塞事件循环。我们使用`bcrypt.hash`的Promise版本。 - **代码片段**：(见`snippets/good_practice.js`) 2. `login(email, password)` - **逻辑**：查找用户 -> 验证密码 -> 生成JWT令牌。 - **注意**：JWT的`secret`必须从环境变量`JWT_SECRET`读取，且令牌过期时间`expiresIn`设置为`7d`。 - **安全**：登录失败返回通用提示“邮箱或密码错误”，避免提示“用户不存在”。 ### 依赖注入 `UserService` 依赖 `UserRepository` 和 `EmailService`。在构造函数中注入，便于单元测试。 ```javascript class UserService { constructor(userRepository, emailService) { this.userRepo = userRepository; this.emailService = emailService; } // ... 方法 }**第五步：总结常见陷阱（COMMON_PITFALLS.md）** 这是AI最能直接提供价值的地方。 ```markdown ## 1. N+1 查询问题 **现象**：在获取用户列表及其所有订单时，先查询用户列表（1次），再循环为每个用户查询订单（N次）。 **错误代码**： ```javascript const users = await User.findAll(); for (const user of users) { user.orders = await Order.findAll({ where: { userId: user.id } }); }解决方案：使用 Sequelize 的include进行急切加载（Eager Loading）。
const users = await User.findAll({ include: [{ model: Order }] });给Claude的提示：当看到需要获取关联数据时，优先考虑使用ORM的关联查询（如include），避免在循环内执行数据库查询。
2. 事务未正确传播
现象：在创建订单并扣减库存时，两个操作不在同一个事务中，可能导致数据不一致。解决方案：使用Sequelize的transaction对象，并在Service层入口处创建事务，传递给所有相关的Repository操作。
await sequelize.transaction(async (t) => { await orderRepository.create(orderData, { transaction: t }); await productRepository.decrementStock(productId, quantity, { transaction: t }); });## 4. 使用策略：如何让Claude“阅读”并应用代码书 构建好知识库只是第一步，关键在于如何有效地将其用于与Claude的交互。这里有几个核心策略： ### 4.1 作为系统提示（System Prompt）的精华版 Claude的对话通常以一个系统提示开始，用于设定AI的角色和行为。你可以将代码书中最核心、最通用的原则提炼成一段简洁有力的系统提示。 **示例：**你是一位资深的后端工程师，是ShopAPI项目的核心维护者。请基于以下ShopAPI项目规范来协助我：
- 架构：我们采用DDD分层架构（API层、服务层、领域层、基础设施层）。控制器要薄，业务逻辑在服务层。
- 异步：统一使用async/await，并用try-catch包裹进行错误处理。
- 数据库：使用Sequelize ORM。查询关联数据时必须使用
include进行急切加载，避免N+1查询。 - 错误：使用自定义的AppError类抛出业务错误。
- 代码风格：文件命名用snake_case，类用PascalCase，变量函数用camelCase。 请严格遵循这些规范来回答所有代码相关的问题。
将这个提示放在对话的开头，Claude会在整个会话中以此为基础进行思考。 ### 4.2 作为上下文（Context）的详细版 当需要处理更具体、更复杂的问题时，系统提示可能不够。这时，可以将相关的知识库文档内容，直接粘贴到你的用户提问（User Message）之前，作为上下文提供给Claude。 **操作流程：** 1. **定位知识**：根据你的问题，找到`claude-code-book`中相关的章节。例如，你要问“如何给UserService添加一个手机号验证的功能”，就找到`CORE_MODULES/user_service.md`和`CODING_STANDARDS.md`中关于服务层和验证逻辑的部分。 2. **提供上下文**：在提问框中，先粘贴这些相关的文档内容，然后用清晰的指令分隔，再提出你的问题。 ``` [以下是ShopAPI项目中关于UserService和编码规范的约定：] （粘贴 user_service.md 中关于UserService职责、依赖注入的部分） （粘贴 CODING_STANDARDS.md 中关于异步处理和错误处理的部分） [基于以上项目规范，请帮我实现以下功能：] 我想在UserService中添加一个`verifyPhone(phoneNumber, code)`方法，用于验证用户手机号。验证逻辑需要调用一个外部的短信服务API（已有SmsService）。请按照项目规范写出这个方法的实现代码，并考虑错误处理。 ``` 3. **Claude的响应**：Claude会基于你提供的详细上下文，生成符合项目特定模式、使用了正确依赖注入、包含了恰当错误处理的代码，而不是一个通用的实现。 ### 4.3 迭代与优化：让知识库“活”起来 代码书不是一成不变的。随着项目演进，你需要更新它。 1. **收集反馈**：在与Claude的协作中，如果发现它反复在某个点上犯错（比如总是忘记用`include`），说明对应的知识库条目可能不够清晰或未被强调。需要回去加强那部分的描述，并添加更醒目的正反例。 2. **纳入新实践**：当团队引入新的技术栈（比如用Redis缓存替换本地缓存）、或者形成了新的最佳实践（比如所有REST API响应包装成`{ code, data, message }`格式），及时更新到对应的`.md`文件中。 3. **版本关联**：可以考虑在知识库的README中注明其对应的主项目代码版本号（如`适用于 ShopAPI v2.1.0+`），避免知识过期产生误导。 ## 5. 效果评估与常见问题 ### 5.1 如何判断代码书是否有效？ 一个有效的`claude-code-book`会带来立竿见影的效果： * **代码一致性提升**：Claude生成的代码，在命名、结构、错误处理方式上，与项目现有代码高度相似，仿佛出自同一人之手。 * **减少纠正次数**：你不再需要频繁地说“不对，我们这里不用`Promise.then`，要用`async/await`”或者“这个查询会引起N+1问题”。AI第一次给出的方案就更接近最终答案。 * **深度理解业务**：对于“为什么这里要这么设计”的问题，Claude能基于你提供的架构文档，给出符合项目背景的解释，而不仅仅是通用的软件工程原理。 * **主动规避已知陷阱**：在建议代码时，AI会主动提及“注意这里需要加事务”或“这个操作建议添加缓存”，因为它“知道”项目历史中这里容易出问题。 ### 5.2 常见问题与解决思路 **问题1：知识库太庞大，一次对话的上下文窗口装不下怎么办？** 这是最实际的问题。Claude的上下文长度有限。 * **策略1：分层摘要**：为每个核心文档（如ARCHITECTURE.md）创建一个简短的“摘要版”（SUMMARY.md），只包含最核心的原则。日常对话使用摘要版作为系统提示。当需要深入某个模块时，再临时提供该模块的详细文档。 * **策略2：精准引用**：不要每次都扔整个文档。训练自己（或通过工具）快速定位到与当前问题最相关的1-2个小节，只粘贴这部分内容。 * **策略3：利用向量数据库（进阶）**：这是更终极的解决方案。将知识库的所有文档切片、转换成向量（Embedding），存入像ChromaDB、Pinecone这样的向量数据库。当用户提问时，先用问题去向量数据库中进行语义搜索，找出最相关的几个文档片段，再将它们作为上下文提供给Claude。这实现了海量知识库的精准、按需调用。 **问题2：Claude有时还是会“忘记”或偏离规范。** * **检查上下文是否充足**：可能你提供的上下文片段恰好遗漏了关键约束。尝试补充更完整的相关章节。 * **强化提示词**：在指令中更明确地强调。“**必须严格遵循**CODING_STANDARDS.md中第3条关于错误处理的规定，使用`try-catch`和`AppError`。” * **分步引导**：对于复杂任务，不要要求AI一步到位。可以分步提问：“第一步，请根据架构，设计这个新功能的API端点路由和控制器方法签名。第二步，请设计对应的服务层接口。第三步，请实现服务层具体逻辑，注意事务。” **问题3：维护知识库增加了额外的工作量。** 确实，初期需要投入。但长远看，它是值得的： * **一次编写，多人（和AI）复用**：它不仅是给AI用的，更是给新加入团队的工程师最好的 onboarding 文档。 * **减少重复沟通**：很多关于“这个项目该怎么写”的讨论，可以直接引用知识库，形成共识。 * **提升代码质量**：通过AI将规范落地到每一次代码生成中，能有效降低代码坏味道。 从我自己的实践来看，为一个中等复杂度的项目构建第一版可用的`claude-code-book`，大约需要投入2-3天的时间。但这笔投资在随后的几个月里，会在代码评审、新人指导以及与AI结对编程的效率提升上，带来远超投入的回报。它让AI从一个“聪明的实习生”，变成了一个“熟悉项目所有历史的资深搭档”。
