Claude 上下文文件

项目名称：内部 API 网关

框架：FastAPI

语言：Python 3.11

编码规范：

• 使用 PEP 8 格式。

• 为所有函数包含类型提示。

• 在三引号中使用文档字符串为所有类和方法编写文档。

• 使用 FastAPI 的 HTTPException 处理错误。

• 避免不必要的全局变量。

• 适用时优先使用异步端点。

架构概览：

• /routes 文件夹包含所有 API 端点。

• /services 处理业务逻辑。

• /models 通过 SQLAlchemy 定义数据库模式。

• /utils 提供共享的辅助函数。

测试：

• 对所有测试使用 pytest。

• 遵循命名模式：test_<模块>_<函数>()

现在，每当你开始一个 Claude 会话时，在给出指令之前，将此上下文文件的内容预先添加到你的提示中。例如：

"根据下面的项目结构和约定，生成一个新的用于管理用户会话的路由。"

然后，Claude 将自动使输出与定义的标准保持一致——一致的命名、文档字符串格式和错误处理。

你也可以让 Claude 审查模块之间的一致性：

"比较这两个路由文件，并识别在命名、文档或异步使用方面的不一致性。"

Claude 可以检测出以下差异：

- `get_user()` 在一个文件中是同步的，而在另一个文件中是异步的。

- 缺失或不匹配的文档字符串。

- 像 `user_id` 与 `uid` 这样的变量名差异。

通过提示 Claude 强制使用你的上下文文件作为参考，你可以在多个贡献者和会话之间维护单一的事实来源。

澄清表：跨提示一致性的策略

| 策略 | 目的 | 实施 | Claude 的角色 |
| --- | --- | --- | --- |
| 上下文锚定 | 保持长期理解 | 将项目目标和标准的摘要粘贴到每个新提示中 | 使代码与定义的规则保持一致 |
| 提示链接 | 逻辑上链接相关会话 | 在继续任务时包含之前输出的摘要 | 保持风格和逻辑的连贯性 |
| 风格执行 | 跨模块标准化代码 | 使用相同的格式和命名指南 | 强制结构统一性 |
| 验证提示 | 自动审计一致性 | 要求 Claude 审查多个文件以发现风格漂移 | 主动检测不一致 |
| 文档强化 | 保持解释统一 | 要求 Claude 使用相同的文档字符串或注释格式 | 保持专业清晰度 |

跨多个提示的一致性是将实验性的 AI 辅助编码与专业的、可维护的工作流程区分开来的关键。通过使用持久上下文文件、结构化提示和可重复的约定，Claude Code 不仅仅是一个助手——而是你工程团队中一个有纪律的成员。

保持一致的语调、格式和逻辑可确保每一段代码都感觉像是由一个统一的开发人员声音精心打造的，即使是在数十个 Claude 辅助会话中生成的。

在下一节中，我们将探讨多文件编辑和同步，其中 Claude 同时协调跨多个模块的更新——确保当系统的某个部分发生变化时，项目的其余部分与之和谐地演进。

## 10.5 示例：重构遗留的单体应用

遗留的单体应用通常从一个单文件的概念验证演变成一个庞大的脚本，将路由、数据访问、验证和业务逻辑混合在一起。它们可以工作——直到不能工作。小型变更变得有风险，测试难以编写，新开发人员难以找到任何东西的位置。在这个示例中，你将获取一个紧凑的单文件 FastAPI 单体应用，并将其重构为一个结构良好的小型应用程序，具有清晰的层级、微小的服务边界和单元测试。目标是在不改变外部行为的情况下实现增量式现代化。

概念开发

良好的重构分离关注点并使依赖关系显式化。在实践中，这意味着四个步骤。首先，在隐藏 SQL 细节的存储库后面隔离数据访问。其次，将规则和横切检查移动到服务层，使路由保持精简。第三，将 I/O 保持在边缘——路由器和数据库助手——以便核心逻辑易于测试。第四，引入一个最小的启动路径来初始化依赖项，而不是全局变量。使用 Claude Code，你引导每一步：描述要分离的内容，请求小单元的完整替换，并在每次更改后通过测试验证行为。

实践示例

下面的遗留单体应用"可以工作"，但将所有内容耦合在一起：全局数据库访问、内联验证以及分散在端点中的业务规则。

创建此文件：