--- name: project-conventions description: "初始化、维护、检查或迁移项目开发约定，包括 UI 设计与交互规范。工程规范默认用根目录 CONVENTIONS.md，设计规范默认用 DESIGN.md；已有明确入口时沿用。普通开发读取现有规范即可，不必完整初始化。" --- # 项目开发规范 让项目约定随代码演进、随仓库共享。只维护项目特有且有依据的内容，不复制全局偏好、工具使用手册或任务进度。 中英文请求均按同一语义处理。回复遵循用户明确语言要求及适用语言约定，否则沿用当前对话的主要语言；已有规范保留原语言，新建规范按用户要求、项目文档语言或对话语言选择。模板标题和说明可翻译，文件名与代码标识保持不变，不因模板是中文而强制输出中文。 ## 按意图工作 - `init/create`：从当前项目提炼规范并建立入口。 - `read/summarize`：读取并回答相关问题，不修改文件。 - `update`：结合当前改动校准相关章节；也用于旧路径迁移。 - `check`：检查改动是否符合约定、规范是否过期，只报告有证据的问题。 没有子命令时按用户意图选择。已授权的开发任务中，稳定约定发生变化即可同步维护现有规范，无需额外确认；只读分析不会触发写入。 ## 位置与职责 - 工程开发规范默认在仓库根目录 `CONVENTIONS.md`；UI 视觉、组件使用与交互规范默认在根目录 `DESIGN.md`。两者均属于共享文件；项目已有明确的规范入口时沿用，不新建竞争正文。 - 用户要求初始化或整理 UI 规范时，没有现成设计规范就创建 `DESIGN.md`，不按篇幅决定存放位置。`CONVENTIONS.md` 只保留设计规范入口，不复制设计正文；整理范围内原先混写的 UI 约定移入设计规范后删除重复内容。普通页面开发或只读检查不自动创建、拆分或迁移规范。 - 根目录 `AGENTS.md` 只保留规范链接与必要的 agent 操作说明。已有开发规则移入规范后删除对应重复段，保留其他有效指令；有实质冲突时先澄清，不靠复制两份解决。 - 本地私有信息沿用全局与项目约定；共享规范只引用位置或配置键。默认位置、真实值的保存、忽略和输出边界由全局“本地私有信息”规则统一定义。 可放入项目 `AGENTS.md` 的最小入口： ```markdown 项目开发约定见 [CONVENTIONS.md](CONVENTIONS.md)。相关开发前读取；改动使已记录的稳定约定变化时，同步更新对应章节。 ``` ## 提炼与维护 1. 用 `git rev-parse --show-toplevel` 定位仓库；非 Git 项目用项目实际根目录。读取适用的项目指令、现有规范和本次相关配置。 2. 检查根目录规范与项目已指定的规范入口；已知路径直接读取，避免被 hidden / ignore 过滤。只读取相关文件，不扫描私有配置的真实值来生成规范。 3. 从包或模块清单、锁文件、配置、入口和代表性相邻实现确认约定。区分用户明确约束与描述性事实；前者注明来源和作用域，后者给出简短依据。单个偶然实现不足以形成规范。 4. 用 [正文模板](assets/templates/project-conventions.md) 作为起点，删除不适用栏目。优先记录入口、边界、复用方式、数据契约和可执行验证命令，避免罗列所有文件或照抄配置。 5. monorepo 在同一正文记录通用约定与 workspace 差异，只更新本次受影响范围。确有长篇专项内容时链接现有文档，不提前建立空目录或成套附录。 6. 完成开发时检查本次变更是否改变已有约定，只更新受影响段落。无变化不重写正文；新规则需要用户约束或稳定实践支持，不能从临时补丁推导。 初始化或明显调整前端页面组织、整理或检查 UI 与交互规范时，按需读 [前端与 UI 识别要点](references/frontend-admin.md)；涉及验证规范时读 [验证识别要点](references/testing.md)。本 skill 维护已确认的约定，探索新视觉方案按需使用设计类能力，不把未确认方案直接写成规范。不默认加载全部参考资料。 ## Git 与规范迁移 - 创建或更新共享规范时，检查 `git ls-files -- ` 与 `git check-ignore -q -- `。若被忽略，用 `-v` 查清来源并用最小的项目级例外使共享规范可被跟踪，不修改全局忽略配置、不使用 `git add -f` 绕过边界。 - 未获提交授权时只准备文件和必要忽略规则，不暂存、不提交；用户要求提交时，相关规范与入口更新应纳入同次提交，不漏掉新建未跟踪文档。 - 用户要求初始化、更新或迁移当前项目规范时，可把已有规范整理到根目录。先检查有无真实凭证或私有数据，按本地私有信息约定处理，再生成共享正文；不直接复制整份原文档进入 Git。 - 新旧文件同时存在时合并有效内容、校准冲突并更新引用，完成后删除已被取代的旧正文。只迁移当前授权范围，不遍历其他项目；旧路径只用于发现与迁移。 - 若旧文件已把敏感值提交到历史中，说明问题但不输出真实值，不擅自改写历史。 ## 检查与交付 检查引用、忽略状态和实际 diff；验证命令以项目配置为准，不为整理规范运行全量构建。简要说明改动、依据、待确认项及共享文件是否已进入用户要求的提交。描述性事实以当前源码、配置和运行结果为准；明确约束不会被源码违例自动覆盖。