.cursor 协作指南

目录结构

• .cursor/changelog/entries/：开发日志 fragment 的唯一数据源。
• .cursor/changelog/changelog-*.md：由生成器确定性生成的只读视图。
• .cursor/changelog/tools/：生成、迁移、合并导入和 hooks 安装工具。
• .cursor/deferred/registry.md：延期决策登记。
• .cursor/pitfalls/pitfalls.md：踩坑记录。
• .cursor/distillery/：问题、洞察和黄金规则。
• .cursor/profile/：项目画像及其变更日志。
• .cursor/plans/：实施计划。

开发日志

每条日志保存为 .cursor/changelog/entries/<author>/<id>.md。以下四个视图由生成器维护，不要手改：

• .cursor/changelog/changelog-full.md
• .cursor/changelog/changelog-recent.md
• .cursor/changelog/changelog-headlines.md
• .cursor/changelog/changelog-by-author.md

python .cursor/changelog/tools/changelog_build.py
python .cursor/changelog/tools/changelog_build.py --check

安装 Git hooks

Windows

powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/install-git-hooks.ps1

Linux / macOS

sh .cursor/changelog/tools/install-git-hooks.sh

pre-commit 会重建并暂存四个视图；post-merge 会在合并后重新生成视图。每个克隆只需安装一次。

导入旧格式日志

仅在需要把旧的聚合日志转换为 fragment 时使用：

powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/merge-import.ps1

sh .cursor/changelog/tools/merge-import.sh

也可将分支或 ref 作为参数传入。导入工具只添加尚不存在的 ID，随后重建并校验视图。

维护约定

• 生成视图只由 .cursor/changelog/tools/changelog_build.py 维护。
• 新记录写入对应模板文件，不在模板中保留其他项目的数据。
• 所有文本文件使用 UTF-8（无 BOM）和 LF 换行。