善弈者谋势，不善者谋子——基于 Zero-Config Code Flow 的 Claude Code 配置使用教程

14.8k
技术类
LLMAIClaude CodeVibe Codingsuperpowers

作者：劳家康 & 韩律元

单位：哈尔滨工业大学，仪器科学与工程学院 & 未来技术学院

日期：2026 年 4 月 6 日

0. 阅读导航 ​

本教程面向希望在 Windows 操作系统上以极低成本快速搭建 AI 编程环境的学生用户。根据读者需求，可以选择不同的阅读起点：

  • 如果希望完全理解作者的思考脉络，建议完整阅读本教程
  • 如果仅仅需要快速配置 Claude Code 环境，建议阅读 使用 ZCF 安装 Claude Code 部分内容
  • 如果已经成功配置 Claude Code 环境，但希望提高 AI 编程产出质量，建议阅读后文中的 常用指令教学 和作为实战演练的 Prompt 工程演示 部分内容

1. 背景介绍 ​

使用自然语言实现程序设计和开发，一直是无数“编程小白”的终极梦想，也是学术界和工业界长期努力的研究方向。近年来，大语言模型（Large Language Models，LLMs）的快速发展，推动了 AI 驱动的开发环境（AI-Driven Development Environments，AIDEs）的长足进步。以 Cursor 和集成 GitHub Copilot 的 Visual Studio Code（VSC）为代表的 AIDEs，凭借智能代码补全和自动化工作流，已经让这一梦想部分实现。来自 Stack Overflow 的行业调查 显示，已有约 84%的开发者将 AI 工具纳入日常开发流程，甚至在部分团队的开发项目中，有近半的代码是由 AI 生成的。可以说，使用 AI 工具编程已是不可逆转的时代潮流。

然而，当广大学生用户将这些 AI 工具应用于实际科研编程任务时，往往面临成本、时间和性能的限制。一方面以 Cursor 为例，其全代码库上下文感知能力和代码补全体验备受好评，但其付费策略对于预算有限的学生用户并不友好；另一方面以 GitHub Copilot 为例，其通过 GitHub Education 计划为学生用户提供免费使用资格，但其在近期的更新中移除了学生用户对 Claude Opus 4.6 等先进模型的访问权限，加之上下文感知能力本就薄弱，面对复杂项目时愈发力不从心。除此之外，以 Trae、Qoder、CodeBuddy 为代表的新兴 AIDEs 性价比颇高，却在模型切换灵活性上存在短板；以 Continue、Roo Code 为代表的开源插件定制性强，却有较高的使用门槛，难以开箱即用。

以上问题促成了以 Claude Code 和 Codex 为代表的下一代编程智能体（Agents）的诞生。此类 Agent 基于命令行界面（Command Line Interface，CLI），通过工具调用、子代理协作、沙盒执行等机制显著提升了自主编程能力，并支持通过上下文协议（Context Protocol，MCP）集成外部工具和服务。在此基础上，技能（Skill）系统进一步将任务流程和领域知识封装为可复用的模块，持续拓展着 Agent 的能力边界。一言以蔽之，用户只需在终端中以自然语言描述需求，此类 Agent 即可产出远超传统 AI 辅助编程方案质量的代码。然而对于中国地区的学生用户而言，使用这些工具并非易事。以 Claude Code 为例，由于官方高昂的资费和不友好的地区政策，诸多用户不得不通过第三方应用程序编程接口（Application Programming Interface，API）曲线救国，并手动集成 MCP 和 Skill 以弥补代理模型与官方模型之间的性能差异。这对于本来就是“编程小白”的学生用户而言，无疑是一道难以逾越的门槛。

基于上述认知，作者于 2025 年 11 月发布初版 教程，彼时以 “What could a soul like that be capable of?” 为引，承载着对 LLM 时代 AI 编程工具的浪漫想象。然而五个月过去，作者必须承认当初的乐观多少有些一厢情愿。这五个月里，以 Coding Plan 为代表的订阅制方案逐渐成熟，客观上降低了使用 Agent 工具的门槛。然而同一时期，OpenClaw 的现象级爆红和随之而来的安全问题，以一种直接的方式提醒了所有人：AI 工具的能力上限，从来不仅取决于模型本身的性能，更取决于智能体的设计成熟度与使用者的工程规范意识。在 AI 辅助编程时代，使用者面对的最小模块不再是一行或一块代码，而是整个功能单元或业务层级，AI 生成的代码不仅要“可运行”，更要“可维护”。“Vibe Coding”绝非良策，“Harness Engineering”方为正途，这正是作者更新本教程的核心动机。

新版教程在保留安装配置流程的基础上，新增两章初版中被忽略的内容：常用指令教学 和 Prompt 工程演示。前者介绍 Claude Code 原生指令与 Superpowers 补充指令的使用方法，帮助读者快速上手；后者通过diffusion_model_implementations这一模块开发案例，系统讲解如何通过 Prompt 工程最大化 AI 编程产出质量，进而拓展 Claude Code 的能力边界。

2. 使用 ZCF 安装 Claude Code ​

2.1 安装 Node.js 环境 ​

根据 ZCF 的项目说明，需要使用以下指令安装 ZCF：

bash
npx zcf

其中，npx 是 Node.js 环境下的包执行工具，因此需要根据读者你的系统环境下载 Node.js 最新长期支持（Long Term Support，LTS）版本的安装包。

Node.js 下载页面链接：https://nodejs.org/zh-cn/download

下载完成后，双击安装包文件进行安装，Node.js 环境的安装过程较为简单，除了需要勾选I accept the terms in the License Agreement选项外，建议全部保持默认设置。

其他系统和硬件架构安装步骤大同小异，在此不再赘述，如有需求可以自行搜索该软件环境的安装教程。

2.2 安装 Git Bash 终端 ​

尽管 ZCF 的安装和 Claude Code 的运行并不依赖 Git 环境，但作者强烈建议 Windows 用户安装 Git Bash 终端。这是因为 Git Bash 终端内置了可移植操作系统接口（Portable Operating System Interface，POSIX）兼容环境，可以显著提升 Claude Code 性能的稳定性，同时也为日后的代码仓库版本管理提供了便利。因此，建议有项目管理需求的读者访问其官网下载最新版本的安装包。

Git Bash 终端下载页面链接：https://git-scm.com/install/windows

下载完成后，双击安装包文件进行安装，Git Bash 终端的安装过程同样简单，除了需要勾选Add a Git Bash Profile to Windows Terminal选项和Use Visual Studio Code as Git's default editor选项外，建议全部保持默认设置。上述两个选项的启用依读者需求而定。

需要说明的是，ZCF 和 Claude Code 完全支持原生 Windows PowerShell 终端，下文所有操作均以 PowerShell 终端为例，无需额外配置。如果读者偏好类 Unix 风格的终端，可以全程使用 Git Bash 终端执行命令，两者的使用方法和效果完全一致。

2.3 安装 ZCF 并执行完整初始化 ​

成功安装 Node.js 环境和 Git Bash 终端后，打开 Windows PowerShell 终端，输入以下命令安装 ZCF：

bash
npx zcf

但是此时往往会遭遇如下错误提示：

bash
npx : 无法加载文件 C:\Program Files\nodejs\npx.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
PowerShell 终端执行策略错误提示

这是因为在默认情况下，Windows PowerShell 终端禁止执行未签名的脚本文件，因此需要修改其执行策略：

bash
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

修改执行策略后，重新打开 Windows PowerShell 终端，即可通过上文的命令成功安装 ZCF。

ZCF 交互配置页面

安装 ZCF 后，需要执行完整初始化流程，以便为读者一键安装配置 Claude Code 及其增效工具，在主页面中输入选项“1”并回车开始初始化，推荐具体设置如下：

  • 选择 Claude Code 配置语言：推荐“English”选项
  • 选择 AI 输出语言：推荐“简体中文”选项
  • 选择 Claude Code 的安装方式：推荐“npm”或者“cmd”选项
  • 选择 API 配置模式：推荐“使用 CCR 代理”选项
  • 选择要安装的工作流类型：推荐全选
  • 选择要安装的输出风格：推荐“工程师专业版”选项
  • 是否配置 MCP 服务：推荐“Yes”选项
  • 选择要安装的 MCP 服务：推荐全选除了“Exa AI 搜索”以外的所有选项

2.4 修改 Claude Code 配置 ​

完成 ZCF 安装和初始化后，Claude Code 已可正常使用。但为使 Windows 用户获得更好的使用体验，建议打开文件%USERPROFILE%\.claude\settings.json，该地址通常对应于C:\Users\your_username\.claude\settings.json，执行如下配置：

json
{
	"env": {
		"DISABLE_TELEMETRY": "1",
		"DISABLE_ERROR_REPORTING": "1",
		"DISABLE_INSTALLATION_CHECKS": "1",
		"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "85",
		"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
		"MCP_TIMEOUT": "60000",
		"ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
		"ANTHROPIC_API_KEY": "sk-zcf-x-ccr",

		// 7897 端口为 Clash Verge 的默认混合代理端口
		// 如果读者使用其他网络代理工具，请根据实际情况修改端口号
		// 如果你不知道此类工具，请忽略下面两行配置，随意配置将导致不可用
		"HTTP_PROXY": "http://127.0.0.1:7897",
		"HTTPS_PROXY": "http://127.0.0.1:7897"
	},

	// ... 其他配置项

	"statusLine": {
		"type": "command",
		"command": "ccline",
		"padding": 0
	}
}

相比于 Claude Code 的默认设置，上述配置主要调整了以下四个部分：

  • 禁用安装检查：Claude Code 默认会在每次启动时执行安装检查并推荐新版安装方法，该信息容易挤占 CCometixLine 状态栏组件的显示空间。通过设置DISABLE_INSTALLATION_CHECKS环境变量即可禁用该检查。
  • 提高上下文自动压缩触发阈值：Claude Code 默认在上下文使用率达到 70%时触发自动压缩，但该阈值并非适用于所有任务，可能导致上下文过早被压缩。通过设置CLAUDE_AUTOCOMPACT_PCT_OVERRIDE环境变量，可将触发阈值调整至更合适的水平。
  • 设置 HTTP 和 HTTPS 代理：除浏览器外，Windows 操作系统中的绝大多数应用程序均不支持系统级代理设置，需要通过设置HTTP_PROXY和HTTPS_PROXY环境变量使 Claude Code 的网络请求能够正确通过代理服务器转发，这在后续安装 Superpowers 时将起到重要作用。如果读者已在系统环境变量中配置了 HTTP 和 HTTPS 代理，则无需重复设置，这是因为 Claude Code 遵守父进程终端配置好的系统代理环境变量。
  • 修改 CCometixLine 的 command：此外，CCometixLine 状态栏组件在 Windows 操作系统下可能出现无法正常显示的问题。依据经验，可通过修改statusLine配置项中的command字段为ccline加以解决。

2.5 配置 CCR ​

完成上述配置后，接下来的关键一步是配置 CCR，以摆脱 Anthropic 官方高昂的资费和地区政策的限制。

在过去半年里，以 Coding Plan 为代表的订阅制方案逐渐成熟，成为学生用户使用 Agent 工具的主流选择。此类方案成本远低于官方按量计费，不过需要注意的是，订阅制方案普遍存在使用数据被用于后续模型训练的问题。如果读者对此存在顾虑，也可以使用 API 密钥按量调用，但成本将显著增加。经过作者的实际测试和综合考量，按性价比从高到低筛选出以下四个平台，供读者权衡选用：

  • MiniMax：

    1. 性价比最高的选择。主力模型 MiniMax M2.7 和 M2.5 参数量均为 230B-A10B，主推的 Plus 套餐仅 49 元/月（490 元/年），支持每 5 小时 1500 次模型调用，并提供极速版套餐选项以满足用户实时性需求，服务稳定性好。
    2. 缺点在于主力模型参数量较小，性能落后于 GLM-5 系列模型和 Kimi K2.5 模型，未针对 Agent 系统进行专项优化，且不提供联网、视觉等 MCP 工具链。
    3. API Base URL：https://api.minimaxi.com/anthropic。

  • GLM：

    1. 综合实力均衡的选择。主力模型 GLM-5.1 参数量达 745B-A44B，主推的 Pro 套餐为 149 元/月（402.3 元/季，1430.4 元/年），提供联网、视觉等全功能 MCP 工具链。模型更新频率最快，新推出的 GLM-5-Turbo、GLM-5v-Turbo 两款加速模型均针对 Agent 系统进行了专项优化，在 Claude Code 中优势明显。
    2. 缺点在于算力资源相对不足，GLM-5 系列除 Turbo 系列外推理速度极慢，且高峰期额度消耗系数达 3 倍。
    3. API Base URL：https://open.bigmodel.cn/api/anthropic。

  • Kimi：

    1. 理论智能水平最高的选择。主力模型 Kimi K2.5 参数量达 1T-A32B，主推的 Allegretto 套餐为 199 元/月（1908 元/年），采用周度/月度限额机制，针对重度开发用户友好。模型原生支持多模态，无需额外调用 MCP 工具链即可完成视觉理解等任务，国内直连稳定。
    2. 缺点在于价格最高，且模型尚未完全针对 Agent 编码系统（即本文的主角 Claude Code 一类工具）进行优化，无法全面发挥性能潜力。
    3. API Base URL：https://api.kimi.com/coding。

  • 云雾 API：

    1. 通用聚合平台，提供包括 Claude Opus 4.6 在内的数百种模型，资费远低于官方 API，调用速度较快，适合救急使用或需要调用官方模型时的替代方案。
    2. 缺点在于按量计费模式对编程 CLI 工具并不友好，成本较难预估，不同分组渠道可能需要配置不同的统一资源定位符（Uniform Resource Locator，URL），且服务稳定性依赖于中转链路。
    3. API Base URL：https://yunwu.ai/v1/。

2.5.1 启动 CCR 服务 ​

打开 Windows PowerShell 终端，输入以下命令打开 CCR 管理页面：

bash
npx zcf ccr
CCR 管理页面

在 CCR 管理页面输入选项“2”并回车打开 CCR UI，注意首次打开 CCR UI 时需要使用登录密钥“sk-zcf-x-ccr”。

CCR UI

2.5.2 填写供应商 ​

在 CCR UI 的供应商选项卡中，选择添加供应商，根据所选的 LLM 服务平台，填写对应信息。作者实际使用的是 GLM 和云雾 API，以下以两者为例：

  • 以 GLM 为例，填写流程如下：

    1. 在”从模板导入”处选择“智谱 Coding Plan”
    2. 在”API 密钥”处填写从 GLM 开放平台获取的 API 密钥
    3. 在”模型”处填写所需调用的模型名称，推荐：“glm-4.7”、“glm-5-turbo”、“glm-5v-turbo”
    4. 点击”保存”

  • 以云雾 API 为例，填写流程如下：

    1. 在”名称”处填写“云雾 API Claude Code”
    2. 在”API 完整地址”处填写https://yunwu.ai/v1/messages
    3. 在”API 密钥”处填写从云雾 API 获取的 API 密钥，并在云雾 API 配置分组为“Claude Code 专属”
    4. 在”模型”处填写所需调用的模型名称，推荐：“claude-opus-4-6”、“claude-sonnet-4-6”
    5. 在”供应商转换器”处选择“Anthropic”
    6. 点击”保存”

  • 提示：

    1. 热门 LLM 服务平台在 CCR 中通常会预置 Claude Code 的 API 配置模板，读者可以直接从“从模板导入”中获取对应的模板，之后依次填写“API 密钥”、“模型”等信息后点击“保存”即可，无需手动填写供应商信息。
    2. 读者在手动填写供应商信息时，“供应商转换器”的选择务必与 API 的格式保持一致：如果 API 为以“v1/messages”结尾的 Anthropic 格式，则选择“Anthropic”；如果 API 为 OpenAI 格式（“API 完整地址”以“v1/completions”结尾），则选择“OpenAI”。

2.5.3 填写路由 ​

在 CCR UI 的路由选项卡中，根据不同任务类型配置模型路由，以 GLM 为例，推荐路由配置如下：

路由类型适用任务模型选择逻辑推荐模型
默认通用任务高性能、中长上下文、短思考、Agent 优化GLM-5-Turbo
后台低优先级任务低成本GLM-4.7
思考高复杂度任务高性能、长上下文、长思考GLM-5-Turbo
长上下文长上下文任务高性能、长上下文GLM-5-Turbo
网络搜索联网搜索任务支持 MCP 联网搜索工具链GLM-5-Turbo
图像图像理解任务支持视觉理解GLM-5V-Turbo

2.6 安装 Superpowers ​

前文提到，相比“Vibe Coding”，“Harness Engineering”才是更可靠的路径。Superpowers 就是一套践行这一理念的技能框架，它为 Claude Code 注入了一套完整的软件开发工作流，涵盖需求澄清、计划编写、测试驱动开发、代码审查等关键环节。与原生 Claude Code 相比，Superpowers 通过自动触发的技能约束，使 AI 代理在编码过程中自动遵循最佳工程实践，显著提升代码质量和可维护性。其详细功能与使用方法将在 常用指令教学 中介绍。

安装完成后，在任意文件夹打开 Windows PowerShell 终端，输入以下命令启动 Claude Code：

bash
claude

在 Claude Code 交互界面中，依次输入以下三条命令即可完成安装：

bash
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
/reload-plugins

2.7 与 IDE 集成 ​

尽管智能体驱动的 AI 横空出世并飞速演化至今，传统的 IDEs 或 AIDEs 依然被绝大多数有编码需求的读者所需要。需要说明的是，VSC 虽在严格分类上属于代码编辑器（Code Editor），但由于其丰富的插件生态已在事实上实现了轻量级 IDE 的功能，因此在本文中也将 VSC 归入 IDE 的范畴。本小节主要以 VSC 为例，详细讲解如何将安装好的 Claude Code 和你现有的 IDE 集成，获得效率与项目掌握的协同统一。

2.7.1 使用 IDE 集成终端运行 Claude Code ​

既然 Claude Code 本身是一个 CLI 工具，而集成终端也是 IDE 最基础的功能之一，那么将 Claude Code 按上文安装成功之后，我们只需要在 IDE 的集成终端中直接运行claude命令，就可以在终端所在目录开启 Claude Code 会话。需要注意的是，与在其他终端中直接使用一样，需要在运行前确保当前目录为项目根目录，并确保进入之前已经为 Claude Code 开启必要环境，这一点在下文的 常用指令教学 会详细介绍。

至于如何快速进入项目所在终端，读者可以在左侧文件资源管理器下，右键项目根目录下任意文件或空白位置并选择“在集成终端中打开”以直接开启位于项目根目录的终端。如下图演示的本文开发界面所示：

在集成终端中使用 Claude Code

上述操作的效果是，在界面偏下位置使用终端和 Claude Code 交互，上方可以正常打开文件，编辑和审阅代码。

值得注意的是，由于 Claude Code 对 VSC 有一定的支持，你在打开的编辑器中选中的任何文字，都可以被 Claude Code 读取到并作为上下文提示词，你的选中会在 CCLine 的最右边，即终端的最右下角显示出来，形如：⧉ 3 lines selected。借助这个特性，你可以通过选中文字，快速便捷地将 Claude Code 的注意力指向你想让它关注的地方去。

2.7.2 使用 IDE 插件运行 Claude Code ​

这是目前大多数用户在 IDE 中使用 AI 辅助编码的方式。前文背景中所介绍的以 Continue、Roo Code 为代表的开源插件，大多都以“面板”（Panel）的方式提供和用户的交互方式。

为了让不熟悉终端的用户快速上手，或是让喜欢使用侧边面板布局的用户得以使用 Panel 运行 Claude Code，Anthropic 官方提供了 Claude Code for VS Code 官方插件，可以打开拓展管理页面（或按快捷键Ctrl+Shift+X），搜索Claude Code for VS Code，选择 Anthropic 官方提供的插件安装即可。

安装后，有三种方式将 Claude 以 GUI 的形式集成到 IDE 中：

  1. 读者应该可以在左侧活动栏（即拓展图标所在的区域）看到 Claude 图标，点击即可在左侧面板侧边栏打开 Claude Code。
  2. 也可以在任意编辑窗口的右上角看到 Claude 图标，点击将默认并列打开新的编辑窗口，启动一个 Claude Code 图形会话。
  3. VSC 还提供辅助侧边栏功能，可以在“查看-外观-辅助侧边栏”中开启，或按Ctrl+Alt+B快捷键显示，该侧边栏收纳如LaTeX\LaTeX开发工具和 Copilot 等辅助编码工具。Claude Code 也应在此列中，选中即可打开 Claude Code 的图形插件界面。

任意一种方式均优先使用本地环境安装的 Claude Code，并使用我们先前对 Claude Code 的配置。如下图所示：

利用插件调用 Claude Code

可以看到，我们先前使用 ZCF 和 Superpowers 所安装的斜杠命令或 Skills 都能正常工作，这证明我们在插件中调用的就是方才安装在本地的那个 Claude Code 实例，说明 VSC 插件本质上是本地 Claude Code 实例的 GUI 封装，共享同一套配置文件和插件系统。

总而言之，无论是横版上下布局还是纵向左右布局，读者都可以根据开发习惯和视觉体验灵活选用。

2.7.3 在 IDE 中审阅 Claude Code 的修改 ​

无论是终端形式还是 GUI 形式，Claude Code 都会自动在合适情况下和 VSC 本身交互。在进行一些重要修改的时候，Claude Code 将在代码编辑器窗口中打开一个代码对比（Diff）窗口并等待读者你的意见。该窗口左侧是原始代码，右侧是 Claude Code 的修改建议，发生改变的部分将以红绿高亮进行标记。如果你在审阅后同意修改，可以点击接受按钮，Claude Code 会将修改应用到你的项目中并继续进行下一步工作。

说句题外话，如果你有使用 Git 版本控制工具来管理项目的优秀习惯，VSC 自带的 Git 功能（插件）也是增强你对 AI 生成代码掌控程度的利器。在左侧活动栏的“源代码管理”功能中，将可以使用 Git Diff 随时查看存储库（Repository）中代码修改。读者还可以随时提交或暂存目前的代码版本，以在出现问题的时候快速且方便地回溯代码仓库。总之，尽管 Git 版本控制和 Claude Code 开发项目并无直接关系，但却可以极大增强你对 AI 生成代码的掌控力。读者若有兴趣，可自行学习 VSC 中的 Git 插件使用和 Git 版本控制工具本身。相信作为久负盛名的版本控制工具，Git 在 Agentic AI 时代仍然会是保障代码质量和开发效率的最基础工具之一。

3. 常用指令教学 ​

安装配置到此结束，接下来聊聊怎么用。本节以一个基于 Conda 环境管理的 Python 项目为例，走一遍 Claude Code 的日常操作：怎么进入项目、怎么规划开发、怎么管理上下文与对话。

3.1 首次进入项目 ​

假设你手头有一个项目要开始——打开项目文件夹，在 Windows 资源管理器的地址栏输入cmd回车，就在当前目录打开了命令行终端；或者在你的 VSC 等 IDE 中从项目目录新建终端。如果项目用 Conda 管理环境，先激活对应的 Python 环境：

bash
conda activate env_name

如果终端里conda命令不可用，说明还没初始化。在 Anaconda Prompt 里执行conda init cmd.exe（Miniforge 用户用mamba init cmd.exe），重启终端即可。不用 Conda 的话这步直接跳过。

环境激活后，输入claude启动 Claude Code。第一次启动会让你选项目目录，选当前目录就行。

如果项目文件夹是空的，后面直接开始干活就行。但如果里面已经有代码，建议先跑一遍：

bash
/zcf:init-project

它会扫描整个项目目录，自动生成CLAUDE.md等上下文文件。相比 Claude Code 自带的/init，/zcf:init-project会额外生成项目索引、Mermaid 结构图和模块导航面包屑，让 Claude Code 更准确地理解项目结构。有文件的项目建议都跑一遍。

3.2 开发工作流 ​

初次使用 Claude Code 的读者最容易犯的错误，就是需求一来直接开写。写了一大堆，回头一看这里不对劲，那也不满意，最后不得不推倒重来，还对模型的能力开始产生怀疑。实际上，这不是模型能力的问题，而是没想清楚就动手的问题——就像装修房子不画图纸，水电工和木工各干各的，最后拼出来的东西很难住人。实施的质量取决于规划的质量。

为了解决这个问题，Claude Code 和 Superpowers 提供了两种分工明确的机制。你可以把它们想象成出发前的两个动作：Plan 模式是打开地图查看地形，头脑风暴则是坐下来规划行进路线。

3.2.1 Plan 模式 ​

Plan 模式是 Claude Code 内置的只读探索机制，通过Shift+Tab或/plan激活，快捷键再按一次退出。激活后，Claude Code 可以读取文件、运行命令，但不会修改任何东西——读代码和改代码是两件事，不应混在一起。接手新项目时快速了解代码库结构，重构前评估依赖关系，都适合用它。安装 Superpowers 后，规划职能由头脑风暴接管，Plan 模式就退回到它最核心的用途：安全地探索代码。

3.2.2 头脑风暴 ​

/brainstorming是 Superpowers 提供的需求澄清工作流，核心定位是“从模糊到清晰”。激活后，Claude Code 不会急于写代码，而是先了解项目现状，再逐一向你提问：需求的目的是什么、约束在哪、怎样算成功。问清楚之后，它会提出两到三种技术方案供你权衡。方案没批准之前，一行代码都不会动。确认之后，它自动生成设计文档，顺势进入计划编写和代码实施阶段，整个过程是连贯的。凡是涉及功能开发或架构设计的任务，建议优先用/brainstorming开头。

3.2.3 实施开发 ​

经过头脑风暴的需求澄清，要构建的内容已经清晰。此时用自然语言描述开发任务，Claude Code 便会开始实施，逐步展示代码变更供读者审查；确认质量可靠后，可切换至Accept edits模式批量接受，提高效率。实施阶段本身并不复杂，它只是在检验前期规划的质量，规划越清晰，实施越顺；规划越模糊，返工越多。好的实施是好的规划自然带出来的结果。

3.3 上下文与对话管理 ​

同一个模型，有时候输出质量很高，代码逻辑清晰、风格一致；有时候却频频出错，甚至把之前交代过的事忘得一干二净。很多人第一反应是模型变差了，但问题往往出在上下文管理上。上下文窗口就像一张书桌：桌面标称能放 200 本书，但真堆满 200 本的时候，你要翻到最底下那本，得先把上面的全搬开。LLM 也是一样，随着对话推进，它对早期信息的注意力会逐渐稀释，指令服从度也随之下降。标称支持 200K 上下文，不意味着在这个范围内都能保持同等质量的输出。

所以上下文管理不只是技术操作，更是一种工作习惯：你在上下文里留了什么，Claude Code 就“知道”什么；你怎么组织它，它就怎么理解你的项目。会管上下文的人，哪怕只用朴素的自然语言，也能获得稳定的输出；不会管的，再好的工作流，跑着跑着也会跑偏。

下面介绍六条常用的上下文管理指令，按使用频率从高到低排列，旨在帮助读者快速学习和认识上下文管理技巧。

3.3.1 /compact ​

最常用的手段是压缩。随着对话推进，细节不断堆积，有用的没用的都挤在上下文里。输入/compact，Claude Code 会对历史对话做摘要，保留关键信息，丢弃冗余，腾出空间继续工作。压缩是有损的，部分细节可能在摘要中被简化乃至遗漏。因此建议主动触发，不要等到输出质量开始下降再补救。

一个实用的节奏是：每完成一轮有意义的对话后主动压缩一次，而不是等到 Claude Code 开始“忘事”才补救。

3.3.2 /clear ​

比压缩更彻底的方式是清空。当对话已经偏离方向，或者需要切换到完全不相关的任务时，在退化的上下文里继续工作只会事倍功半。输入/clear，Claude Code 会清除全部对话历史，重新开始。CLAUDE.md等项目文件不会因此受到影响，Claude Code 仍能从中读取项目背景。清掉的是对话历史，不是项目本身的上下文。

典型场景：上一个功能做完了，接下来要开始一个完全不相关的新任务。

3.3.3 /rewind ​

有时候不需要全部清空，只是某一步走错了，后面越跑越偏。输入/rewind，选择对话中的某个历史节点，该节点之后的文件变更会被自动撤销，从那里重新出发。与其让一个错误在后续对话中持续放大，不如及时回退。

典型场景：Claude Code 改错了一个关键文件，后续的修改都建立在这个错误之上，这时候回退到出错之前的节点比手动逐个撤销要高效得多。

3.3.4 /resume ​

许多任务无法在一次对话中完成，关掉再打开默认就是全新的上下文，之前的进度就断了。输入/resume可恢复上一次的对话上下文，自动匹配最近一次对话；也可以在启动时从对话列表中选择任意历史对话恢复，按需衔接。

3.3.5 /diff ​

如果项目在 git 仓库中，输入/diff可以查看所有未提交的代码变更，还可以按对话轮次逐条回看 Claude Code 每次修改了什么。管理对话时，知道自己做了什么和知道自己还能做什么同样重要。尤其在准备提交代码之前，用它过一遍所有变更，能有效避免遗漏或误改。

3.3.6 /btw ​

Claude Code 正在执行任务时，如果临时想到一个问题，不必等它干完。输入/btw <你的问题>，它会立刻回复，当前任务不受影响，且这条消息不会计入主对话上下文，不占额外空间。

典型场景：执行过程“卡住了”，问问他怎么了；产生了一个 plan，你有地方没看懂，但是不想干扰正常的规划-执行流程。

3.4 从 Tips 中学习更多进阶用法 ​

读者在使用 Claude Code 的实践过程中，若留心终端界面往往会发现：如游戏的加载界面一般，一些小提示（Tips）会适时的出现在正在执行的任务中。如果你感兴趣，不妨试试提示给出的命令/操作/快捷键，或许能帮你发现一片新的天地。

4.Prompt 工程演示 ​

4.1 反思 ​

相信用过 ChatGPT 等 WebChat 工具的读者，都经历过这样的工作流：把需求丢给 AI，等待它输出代码，然后粘进 IDE 里测试，如果能用就万事大吉，如果报错就再问一轮。单文件小项目里这套流程确实顺畅，在一个对话窗口中持续对话几轮，就能完成一整份代码。但项目规模一旦大到需要拆分多个文件，问题就来了：先看注释和 docstring，这份代码用中文和 Sphinx 风格写，那份代码用英文和 Google 风格写，还有份代码直接不写；再看变量名，同样是获取图像，这个文件里叫getImage，那个文件里叫get_image，还有高手直接来个fetch_data。单独看每个文件似乎都差强人意，合在一起就让人接受不能。

根源在于一个经常被人忽视的事实：LLM 的上下文窗口总是有限的。这就好比你在一块固定大小的白板上写字——写满了就得擦，问题只在于擦哪些。WebChat 时代的上下文传递只有三种模式：完全保留、自动压缩和自动截断。完全保留会导致上下文长度快速膨胀，你在早期对话中强调的内容，在长对话后大概率已经被淹没在上下文的噪声中；自动压缩虽然能有效控制上下文长度，但是压缩过程不可能是无损的，只能做到关键信息的保留；至于自动截断则更为简单粗暴，直接丢弃早期对话内容。可以说，不论采用哪种方式，随着对话轮次的增加，接口不一致和风格漂移都是不可避免的结果。

AIDEs 和 CLI 工具的出现缓解了上述问题，它们能够自动读取项目文件并构建上下文，开发者不再需要每次重新交代项目背景。但缓解不等于解决，此类工具解决的是“AI 看不到代码”的问题，却没有解决“AI 不知道你想要什么样的代码”的问题，因此它们能够降低跨文件接口不一致的风险，却无法获知你对接口契约、编码规范的期望。不主动建立约束，AI 就只能按照自己的判断行事，而每次的判断都可能不同。

Prompt 工程的价值正在于此：不是“把需求说清楚”这么简单，而是系统地为 AI 建立一套信息框架，让它的输出从“能用”升级为“可维护”。本节利用仓库里的 diffusion_model_implementations 项目做案例，讲这套框架的三层结构：精确定义接口契约、建立统一的编码范式、用架构承载规范。三层递进，先把方向定对，再把标准立好，从而确保代码实现符合预期。

4.2 精确定义接口契约 ​

很多人遇到代码结构混乱时，第一反应是“Prompt 是不是不够长”，然后拼命往对话里塞细节，背景、需求、约束堆一大段。AI 确实输出了更多文字，但接口不一致、模块耦合等核心问题依旧存在。问题从来不在 Prompt 有多长，而在是否精确定义了接口和结构。一千字的泛泛描述，不如三百字的精确规格。

上一节说过，装修不画图纸，水电工和木工各干各的，拼出来的东西很难住人——接口定义在多文件协作中扮演的就是图纸的角色。一旦方法签名、参数类型、返回值形状被确定，AI 就没有“自由发挥”的余地，它不会在一个实现里把参数名改成input，在另一个实现里改成data；不会在这个算法里加一个guidance_scale参数，在另一个算法里省掉。

4.2.1 需求文档长什么样 ​

精确的接口定义可以来自多种渠道：与擅长长思维链推理的模型充分讨论后整理为 Markdown 文档，例如 Gemini 3.1 Pro、GPT 5.4 Pro，或在 Claude Code 中直接使用/brainstorming进行结构化头脑风暴，它会在讨论结束后自动生成设计文档。当然也可以手动编写，形式不限，核心都是为 AI 提供精确的接口和结构定义。

diffusion_model_implementations项目的需求文档（docs/idea.md）就是一个例子。它做了三件关键的事。

(a) 确定文件结构

bash
diffusion_model_implementations/
├── config.yaml
├── runtime.py
├── diffusion_implementations/
│   ├── __init__.py
│   ├── ddpm.py
│   ├── ddim.py
│   ├── sde_solver.py
│   └── dpm_solver.py
└── models/
    ├── __init__.py
    ├── unet.py
    ├── dit.py

四个算法各一个文件，两个模型各一个文件，runtime.py负责调度，config.yaml负责配置。没有歧义，没有自由发挥的空间。不写这一段，AI 很可能把四个算法塞进同一个文件，或者自己发明一个多余的utils.py。

(b) 确定接口签名

扩散算法的三个核心方法：

python
def forward_sample(self, x_0: torch.Tensor, t: int) -> torch.Tensor:
    """
    前向加噪：从 x_0 直接采样到 x_t
    """

def reverse_sample(self, x_t: torch.Tensor, t: int, condition: Optional[torch.Tensor], model: nn.Module) -> torch.Tensor:
    """
    单步反向去噪：给定 x_t，预测噪声并计算 x_{t-1}的分布后采样
    """

def reverse_sample_loop(self, shape: Tuple[int, ...], condition: Optional[torch.Tensor], model: nn.Module) -> torch.Tensor:
    """
    完整反向采样循环：从纯噪声逐步去噪到 x_0
    """

噪声预测模型的统一接口：

python
def forward(self, x_t: torch.Tensor, t: torch.Tensor, condition: Optional[torch.Tensor]) -> torch.Tensor:
    """
    预测噪声，输出形状与 x_t 一致
    """

每个方法的参数名、参数类型、返回类型全部被精确确定。forward_sample接收x_0和目标时间步t；reverse_sample额外接收可选张量condition和model；reverse_sample_loop不需要t但需要shape。这些设计不是随意的，前向过程直接按噪声调度加噪，反向去噪需要外部指定当前时间步，而完整采样循环内部自行遍历所有时间步。condition的类型是Optional[torch.Tensor]而不是torch.Tensor，因为无条件生成时需要传None。这种精确定义消除了 AI 在实现时自行决定类型的空间。

© 确定配置结构

yaml
diffusion:
  implementation: "ddpm"
  timesteps: 1000
  beta_start: 0.0001
  beta_end: 0.02
  beta_schedule: "linear"

model:
  type: "unet"
  in_channels: 1
  out_channels: 1

配置驱动是现代软件工程的基本理念。运行时决策从代码中抽离，放进配置文件，切换算法只需改一个字符串。需求文档不仅定义了配置结构，还要求 AI 对不支持的配置值快速失败并抛出清晰异常，这就把错误处理行为也提前约束了。

4.2.2 验证：定义什么，AI 就产出什么 ​

按照上述方法，你应该能观察到一个直接的效果：AI 产出的代码签名与需求文档完全一致，不多一个参数，不少一个类型。随便打开两个算法文件对比一下：

python
# ddpm.py
def forward_sample(self, x_0: torch.Tensor, t: int) -> torch.Tensor:

# dpm_solver.py
def forward_sample(self, x_0: torch.Tensor, t: int) -> torch.Tensor:

四个算法文件都是这个签名，两个模型的forward也是同理——参数名、参数类型、返回类型一个字都没差。不需要在 Prompt 里写“请保持接口一致”之类的模糊指令，只要把接口定义写清楚，一致性是自然而然的结果。

4.3 建立统一的编码范式 ​

上一节解决了“做什么”的问题。但接口一致只是第一步。

你可以把接口契约想象成乐谱上的旋律线——它规定了每个乐手演奏什么音符，但没有规定弓法、指法、呼吸。让 AI 实现多个文件时，风格漂移几乎是必然的：一个文件用中文写 docstring，另一个用英文；一个函数补全了完整的类型提示，另一个只写了个def；一个文件的注释写在代码上方，另一个文件的注释缩在行尾。这种问题靠需求文档解决不了，需求文档管的是接口契约，管不到演奏风格。靠在 Prompt 里口头提醒也不靠谱，“请保持代码风格一致”太模糊，AI 每次对“一致”的理解都可能不同。

需要一份专门的编码约束文档。这比需求文档更重要：需求文档通常只写一次，管的是“做什么”；编码约束每次写代码都要遵守，管的是“怎么做”。

这里有一个容易踩的坑：很多人把精力花在纠结“docstring 该用中文还是英文”“变量名该用 camelCase 还是 snake_case”此类风格选择上，但选择本身并没有绝对的对错之分，真正重要的是不管选了哪一边都写清楚，并且确保 AI 每次执行同一套标准。下面展示的是diffusion_model_implementations项目的编码规范，选择了一套适合中文教学项目的约定。你的项目完全可以做出完全不同的选择，比如 docstring 全部用英文、命名采用 camelCase。重点不在于“这些规则是什么”，而在于“这些规则是如何被定义和执行的”。

4.3.1 设计理念：可执行、可检查、可复述 ​

写编码规范很容易走两个极端。一个极端是干脆不写，“AI 写代码应该有自己的风格判断”，然后得到一堆风格各异的文件，审查时不知道该以哪个为准。另一个极端是写一大堆，把 PEP 8 全文贴进去，洋洋洒洒几十页，然后 AI 根本无法从中提炼重点。

中间路线的核心信条只有一句话：

代码应写得像稳定的工程契约，而不是临时的个人表达

围绕这个信条，每一条规则都应该满足三个标准：

  • 可执行：AI 或工程师可以直接据此行动，不需要猜测
  • 可检查：审查时可以明确判断某行代码是否命中规则
  • 可复述：规则可以被稳定地转写为 prompt 或 skill，反复使用

这三个标准是通用的，跟具体选了什么风格无关。不管你规定 docstring 用三行还是一行、注释用中文还是英文，只要规则满足这三个标准，AI 就能稳定执行。

整份文档建议分三层结构：判定规则（定义“必须”“禁止”等术语的精确含义）→具体规范（命名、类型提示、docstring、注释、文本语言等）→审查清单（逐条勾选）。不是规则越多越好，而是每一条都经得起追问：这条规则，AI 看了之后知道该怎么执行吗？

4.3.2 具体规范：四条消除歧义的规则 ​

下面从“要解决什么问题”的角度，看这个项目选择了哪四条规则。再次强调，这些规则本身不是重点，重点在于每一条规则都是可执行、可检查、可复述的。

(a)Docstring 的唯一合法形态 ​

这是本份规范里最“斤斤计较”的一条。它规定 docstring 的最小合法形态是固定的三个物理行：

python
def load_config(config_path: str) -> Dict[str, Any]:
    """
    读取 YAML 配置文件并返回配置字典
    """

三双引号各自独占一行，摘要写在中间，一行都不能少。而下面这种写法属于违例：

python
def load_config(config_path: str) -> Dict[str, Any]:
    """读取 YAML 配置文件并返回配置字典"""

三引号和摘要挤在同一行，不行。哪怕内容完全一样，形式不对就是不对。

为什么在“看起来差不多”的细节上较真？因为规则的价值不在于某一行代码的美感，而在于消除歧义。如果允许两种写法并存，AI 在同一个项目里就会随机选择，有时写三行有时写一行，审查时标准也不统一。规定唯一合法形态，就把这种随机性彻底消灭了。当然，你也可以规定唯一合法形态是单行写法，效果是一样的——关键不在于选了哪种，而在于只选了一种。

当需要字段块时，规范同样给出了精确格式。来看一个真实例子，diffusion_implementations/__init__.py中build_diffusion的 docstring：

python
def build_diffusion(config: Dict[str, Any]) -> nn.Module:
    """
    根据配置字典构建扩散算法实例

    Args:
        config: diffusion 配置字典，必须包含 implementation 字段，
            其他字段根据具体算法传递

    Returns:
        构建好的扩散算法实例

    Raises:
        ValueError: 不支持的 implementation 值或缺少必要配置
    """

三双引号独占一行；摘要独占一行且只写一行接口契约；摘要与Args:之间空一行；参数名与冒号对齐，描述文本保持缩进；Raises:精准列出调用方需要处理的异常。每一条都有据可查。

(b) 命名使用完整单词 ​

本份规范要求“默认使用完整单词，禁止省略、截断和习惯性缩写”。来看一个反面场景：同一个概念，如果命名不约束，AI 可能在一个文件里叫ch，另一个文件里叫emb，还有一个文件里直接用h，根本分不清它是 height 还是 hidden。

实际项目中的做法是严格遵守完整单词命名。DDPM类的构造函数就是一个例证：

python
def __init__(
    self,
    timesteps: int,
    beta_start: float,
    beta_end: float,
    beta_schedule: str = "linear",
) -> None:

timesteps而不是T或steps，beta_start而不是b0或bs。_ResBlock的构造函数同样如此：

python
def __init__(
    self,
    in_channels: int,
    out_channels: int,
    time_embed_dim: int,
) -> None:

in_channels而不是ic或ch_in，time_embed_dim而不是ted或t_dim。

缩写仅在极少数窄场景下被允许：参数名后缀如embed_dim、num_classes，业界固定导入别名如np、nn，张量形状解包如B, C, H, W = x.shape。除此之外，一律用完整单词。当然，如果你的团队习惯用缩写，完全可以规定一份“缩写词表”作为规范的附录，把允许使用的缩写及其全称一一列出。做法不同，但原理一样：消除命名时的自由发挥空间。

© 公有接口补全类型提示 ​

所有公有函数和方法都要求补全参数类型与返回值类型。这不是装饰品，而是代码契约的一部分，让 IDE 提供准确的自动补全，让静态分析工具捕获类型错误，让读代码的人一眼知道该传什么、会返回什么。

runtime.py中的三个函数是这方面的范例：

python
def load_config(config_path: str) -> Dict[str, Any]:
    ...

def build_from_config(
    config: Dict[str, Any],
) -> Tuple[nn.Module, nn.Module, Dict[str, Any]]:
    ...

def get_device(config: Dict[str, Any]) -> torch.device:
    ...

三个函数，每一个都包含完整的参数类型和返回值类型。build_from_config的返回值是一个三元组，类型被精确声明为Tuple[nn.Module, nn.Module, Dict[str, Any]]，调用方不需要去猜第一个元素是扩散算法还是模型，类型说明里写得清清楚楚。

AI 生成代码时，如果规范要求补全类型提示，它对类型的把握也会更准确，不会出现“本来该传int结果传了str”这种低级错误。

(d) 源码文本统一使用中文 ​

docstring、注释、内部 logger、内部异常文本，全部默认使用中文。

python
# 预计算前向过程所需系数
self.register_buffer("betas", betas)
self.register_buffer("alphas", alphas)
self.register_buffer("alphas_cumprod", alphas_cumprod)
python
raise ValueError(f"不支持的 dpm_solver.order: {order}，支持的值为：[1, 2]")

面向中文用户的中文项目，源码文本用中文，阅读成本最低。这条规则不是在争论“中文好还是英文好”，而是在消除“这次用中文、下次用英文”的随机选择。统一了语言，就不会出现同一个项目里 docstring 一半中文一半英文的情况。如果你的项目面向国际用户，把这条换成“源码文本统一使用英文”即可，效果完全一样。

4.3.3 当规范生效时 ​

当接口契约统一了“做什么”，编码范式统一了“怎么做”，AI 生成的代码就会呈现出高度一致的品质感。来看DDPM类的实际 docstring：

python
class DDPM(nn.Module):
    """
    提供前向加噪与反向去噪的扩散采样接口
    """

    def __init__(
        self,
        timesteps: int,
        beta_start: float,
        beta_end: float,
        beta_schedule: str = "linear",
    ) -> None:
        """
        构造 DDPM 并预计算噪声调度系数

        Args:
            timesteps:     总扩散步数 T
            beta_start:    噪声调度起始值
            beta_end:      噪声调度终止值
            beta_schedule: 调度策略，支持"linear"和"cosine"
        """

逐条核对这份规范中的规则：三双引号各自独占一行；摘要独占一行且不加句号；Args:的说明列纵向对齐；没有模块级 docstring；签名包含完整的参数类型和返回值类型；参数名使用完整单词；docstring 使用中文。每一条都精确命中。这就是编码约束文档想要达到的效果。不是要求你的项目也采用完全相同的规则，而是希望你能像这样，用可执行、可检查、可复述的标准，消除 AI 输出中的随机性。

4.4 用架构承载规范 ​

到目前为止，前两节解决了两个问题：精确定义接口契约（做什么），建立统一的编码范式（怎么做）。但有一个更底层的问题还没回答：同样一份编码规范，为什么在结构清晰的项目里效果很好，在面条代码里毫无作用？

答案很直接：代码架构决定 Prompt 的效力上限。还是用盖房子来打比方——图纸画得再漂亮，如果地基是歪的、墙体没有承重结构，装修工人也没法按图施工。代码架构就是这个地基和承重墙。你在代码中做出的每一个结构选择，都在同时决定 AI 能以多高的效率理解并遵守你的规范。

架构决策启用了什么
工厂函数模式配置驱动才有意义，改一行配置切算法，不需要碰任何代码
单文件单职责编码规范才能逐文件审查，每个文件的职责清晰，风格检查才有抓手
统一接口签名docstring 才能成为可靠契约，AI 读到一个函数的 docstring，就能推断所有同类函数的行为
清晰的模块边界分层放置策略才成立，不同类型的信息天然属于不同的模块层级

用diffusion_model_implementations项目来验证。

工厂函数模式：diffusion_implementations/__init__.py中的build_diffusion和models/__init__.py中的build_model就是两个工厂函数。它们读取配置字典，根据implementation或type字段动态构建对应的实例。切换算法只需修改配置，不需要改动任何业务代码。如果代码里没有工厂函数，配置驱动就是空谈。

单文件单职责：ddpm.py只管 DDPM，dit.py只管 DiT，runtime.py只管配置加载和构建。每个文件做什么，从文件名就能看出来。这种结构让编码规范可以逐文件审查，审查ddpm.py时，不需要关心 DiT 的实现细节。

统一接口签名：四个扩散算法共享同一套方法签名，两个模型共享同一个forward签名。AI 读到一个算法的 docstring，就能准确推断其他三个算法的行为。如果每个算法的接口都不一样，docstring 再规范也没有参考价值。

清晰的模块边界：diffusion_implementations/管算法，models/管网络结构，runtime.py管调度，config.yaml管参数。四个模块各司其职，边界清晰。这种结构直接决定了信息天然属于哪一层。

4.4.1 信息分层放置 ​

当架构足够清晰，信息的分层放置就不是人为规定的，而是架构自然推导出来的。越通用的信息放得越稳，越具体的信息放得越近。

放置位置本项目案例生效范围
全局上下文diffusion_model_implementations/CLAUDE.md所有对话
需求规格docs/idea.md特定功能开发
编码规范docs/coding_standards.md所有代码文件
接口契约各函数的 docstring单个函数调用方
运行时配置config.yaml每次运行

全局上下文放在CLAUDE.md中，因为项目的基本信息在所有对话中都需要，架构决定了这是项目级的知识。需求规格放在docs/idea.md中，因为它只在开发特定功能时才需要，架构的模块边界决定了这是功能级的知识。编码规范放在docs/coding_standards.md中，因为编写任何文件时都应该遵守，这是跨模块的横切关注点。接口契约写在 docstring 里，因为 AI 读到那个函数时自然能看到，单文件单职责的架构让这种内聚成为可能。运行时参数放在config.yaml中，因为工厂函数模式让配置驱动成为现实，改一行配置切算法，代码一行没动。

说到底，架构和规范不是两件独立的事。地基不稳，图纸再漂亮也没用。

4.5 预期效果与验证方法 ​

前三节讲的是方法，这一节看效果。当接口契约、编码范式和代码架构三层到位之后，AI 的产出会呈现出几个明显的特征。

4.5.1 接口一致性 ​

这一点在 4.2 已经展示过：四个算法的forward_sample和两个模型的forward签名完全一致，参数名、参数类型、返回类型一个字都没差。精确的规范约束了 AI 的输出空间，一致性不是偶然的。

4.5.2 代码风格一致性 ​

编码范式生效后，不同文件的代码会呈现出统一的品质感。4.3 节展示了DDPM类的 docstring，这里再看UNet类的：三双引号各自独占一行，中文摘要不加句号，Args:说明列纵向对齐，参数名使用完整单词，签名包含完整的类型提示。和DDPM一模一样的格式，和DiT也一模一样。这不是巧合——同一份规范约束下，风格一致是自然的结果。

4.5.3 配置驱动 ​

三层方法论叠加后，最终体现为一个朴素的效果：改一行配置，切换整个算法或模型，代码一行没动。

比如在config.yaml中把扩散算法从 DDPM 换成 DPM-Solver：

yaml
diffusion:
  implementation: "dpm_solver" # 原来是"ddpm"，改这一个字段就够了
  timesteps: 1000
  beta_start: 0.0001
  beta_end: 0.02
  beta_schedule: "linear"
  dpm_solver:
    order: 2
    steps: 20

切换的桥梁是工厂函数。build_diffusion读取implementation字段，动态构建对应的实例：

python
def build_diffusion(config: Dict[str, Any]) -> nn.Module:
    implementation = config.get("implementation")
    # ... 校验逻辑 ...
    if implementation == "ddpm":
        return DDPM(**common_kwargs)
    elif implementation == "dpm_solver":
        dpm_config = config.get("dpm_solver", {})
        return DPMSolver(**common_kwargs, order=dpm_config.get("order", 2), steps=dpm_config.get("steps", 20))

模型侧的build_model也是同样的模式。配置驱动不是某个单独环节的功劳，而是需求定义、编码规范和代码架构三者协同的结果。

4.6 本节小结 ​

回到最初的问题：怎么让 AI 生成可维护的代码？

答案不是写更长的 Prompt，而是搭一套框架让 AI 在里面稳定发挥。这个框架有三层：接口契约告诉它做什么，编码范式告诉它怎么做，代码架构则决定了前两层能不能真正落地。三层都到位，AI 的产出就是稳定的；缺任何一层，都会在某个环节开始漂移。

如果你读完想动手试试，可以从三件事开始：

  1. 写一份需求规格，放在项目docs/目录下。不需要很长，但每个公有方法的签名、参数类型、返回值和配置结构都要写清楚
  2. 写一份编码约束，挑四到六条对你的项目最重要的规则。docstring 格式、命名规则、类型提示，这三个方向最值得优先约束
  3. 整理代码架构。工厂函数、单文件单职责、统一接口签名——这三个决策能最大化前两份文档的效力

所有这些，说到底就是一句话：你给 AI 搭的舞台有多稳，它的表演就有多靠谱。

基于 Zero-Config Code Flow 的 Claude Code 配置教程