cookiecutter

Cookiecutter 模板开发

在修改包含 cookiecutter.json、hooks/ 或 {{ cookiecutter.project_slug }}/ 等生成项目目录的仓库之前，请先使用此技能。

初步检查

1. 编辑前，先阅读仓库说明、README.md、cookiecutter.json、现有测试以及所有钩子。
2. 找出模板根目录和生成项目根目录。请修改模板文件，而不是某个渲染后的示例。
3. 添加新变量前，先用 rg 搜索相关的 Cookiecutter 变量和功能开关。
4. 检查仓库如何验证渲染后的项目。优先使用现有的渲染测试和冒烟检查命令，不要另行设计验证流程。

模板边界

• cookiecutter.json 是面向用户的接口。每个新增提示词、默认值、派生值、私有值和选项都应经过审慎设计，并在仓库说明选项的地方记录。
• 生成项目目录中的文件名和路径本身也可能包含 Jinja。请将文件内容和路径都视为渲染对象。
• 遵循仓库当前的变量风格。如果已有功能开关使用 y/n 字符串，新增开关也沿用这种风格。如果使用 Cookiecutter 布尔值，则继续使用真正的 JSON 布尔值。
• 可选功能在启用和禁用时都必须有效。请一并移除或控制应用文件、导入、URL 路由、设置、依赖项、文档、测试、工作流和迁移。
• 不要在生成内容中加入维护者专用名称、本地路径、密钥或针对单个 Agent 的假设。

Jinja 规则

• 确保渲染后的文件在其目标语言中有效：Python、JSON、TOML、YAML、shell、Markdown、HTML、JavaScript 或 CSS。
• 注意条件块后是否出现多余的逗号，尤其是在 JSON、TOML、Python 数据结构、YAML 列表、包清单和 GitHub Actions 中。
• 仅在能改善渲染后的语法或格式时使用空白控制（{%- ... -%}）。验证渲染结果，而不只是模板源文件。
• 将字符串插入代码或数据文件时，请使用安全序列化。如果仓库已有 JSON/Jinja 过滤器用法，例如 |tojson，请优先沿用。
• 如果生成内容必须保留字面的 Jinja、模板语法或 Agent 占位符，请转义花括号、用 raw 块包裹内容，或将路径添加到 _copy_without_render。
• _copy_without_render 会阻止渲染文件内容，但仍会渲染路径。若需原样复制整个目录树，请同时添加目录项和递归 glob 项。

钩子

• 将 Cookiecutter 钩子脚本放在 hooks/ 中，命名为 pre_prompt、pre_gen_project 或 post_gen_project。除非仓库明确只面向特定平台，否则跨平台模板优先使用 Python。
• pre_gen_project 和 post_gen_project 在生成项目根目录中运行，可以使用已渲染的 Cookiecutter 变量。
• 钩子应具有确定性、幂等性，并使用相对路径。避免网络请求、密钥、交互式提示和机器本地路径。
• 钩子以非零状态退出会停止生成，Cookiecutter 也会清理生成的目录。对无效用户输入应尽早失败；清理操作则应尽量稳健。
• 整个可选文件或目录的清理应使用生成后清理。对于必须保留的小型、语法相关文件改动，请使用内联 Jinja。

测试

• 添加或更新测试，使用明确的上下文值渲染模板。 在可行时，针对每个已更改的选项，分别覆盖启用和禁用的情况。
• 不仅要断言内容存在，也要断言内容不存在：禁用可选功能后，不应残留导入、依赖项、路由、文档、工作流、迁移或占位文本。
• 如果更改了生成行为、钩子、模板选择或命令行假设，请使用真实的 Cookiecutter CLI 进行测试。
• 如果更改了运行时行为，请在临时目录中生成项目，并运行该项目文档中列出的检查。
• 检查对语法敏感的渲染文件：JSON、TOML、YAML、Python 模块、shell 脚本和包清单。

常见失败模式

• Jinja 将语法有效的模板源代码渲染为无效的生成代码。
• 禁用某个选项后，虽然移除了文件，却残留了设置、导入、URL、依赖项、文档、测试、迁移或 CI 引用。
• 原本要留给生成项目的字面量 {{ ... }} 占位符被 Cookiecutter 消耗。
• 钩子将模板仓库误认为是工作目录，而非生成项目的根目录。
• 测试只渲染了一种理想场景下的上下文，却遗漏了其他受支持的选项组合。
• 生成的文件中包含本地路径、个人姓名、密钥，或对特定 AI 工具的假设。

完成标准

• 在模板层面进行模板更改。
• 相关的启用和禁用选项组合均可成功渲染。
• 生成的输出中没有过期占位符、语法错误、无主导入或维护者专属的硬编码值。
• 仓库的模板测试套件通过。
• 如果用户或生成项目的贡献者需要了解更改，请更新文档和变更日志条目。

参考资料

• 官方文档：https://cookiecutter.readthedocs.io/en/stable/
• 上游仓库：https://github.com/cookiecutter/cookiecutter