分享下我自己的项目维护 SKILL

---
name: xingrz-project-conventions
description: 在为 XiNGRZ 新建、开发或维护代码项目时应用其工程约定，包括 Git 身份、提交整理、项目文档、产品交互与交付验证。不用于普通问答或非代码文档创作。
---

# XiNGRZ 项目规范

在用户指定的仓库中持续维护项目，遵循当前项目约定和当次明确要求。语言、许可证、技术栈和视觉风格按项目决定，不预设统一选择。

## 工作范围

- 自主完成已授权范围内的实现、修复、验证和合理粒度的本地提交。遵守“先体验”“只提交不推送”等阶段限制；提交、推送、部署和发版分别按当次授权处理。
- 控制修改的影响面。未经明确允许，不自行修改当前项目之外的仓库。确有必要时，先说明具体原因、拟改内容及影响范围，并明确询问；已有授权覆盖该范围时无需重复确认。

## Git 身份与新仓库

- 个人项目通常使用 `XiNGRZ `。
- 公司项目通常使用 `▓▓▓ <▓▓▓▓▓>`。
- 提交前核对仓库用途与实际生效的 author、committer 身份，例如检查 `git var GIT_AUTHOR_IDENT`、`git var GIT_COMMITTER_IDENT`，必要时检查仓库级 Git 配置及环境覆盖。不要因为已有配置或全局默认值就假定身份正确，尤其注意公司项目遗忘配置的情况。
- 项目归属明确时，在需要的仓库设置 `git config --local user.name` 和 `git config --local user.email`；不修改全局身份。归属不明且会影响身份选择时，先询问。用户明确指定的身份优先。
- 开新项目时，先确定并配置提交身份，再在尚无提交的仓库执行 `git commit -m "Init repository" --allow-empty`，建立方便后续 rebase 的初始 HEAD。不要把项目文件放进这条提交；若已有暂存文件，先保留其内容与暂存状态，使这条提交确实为空。已有历史的仓库不补造初始提交。
- 这条空初始提交使用精确消息 `Init repository`，是下述 Conventional Commits、正文和 AI co-author 格式的例外。

## 提交与历史整理

- 使用 Conventional Commits。标题简短，说明做什么；正文简要解释为什么，按 75 字符硬换行。提交语言遵循项目惯例和用户建立项目时的要求，不固定为中文或英文。
- 每条普通 authored commit 末尾添加 `Co-authored-by: <实际 AI 模型名称和版本> <对应邮箱>`。使用运行环境明确提供的模型身份，不猜测更细版本，不冒用其他模型；OpenAI 模型使用 `noreply@openai.com`。AI co-author 不替代用户的 author／committer 身份。不要将 trailer 强行折行。
- 按完整、可审阅的逻辑组织提交，避免留下相互抵消、反复修改同一问题的提交链。在授权范围内，把后续修正折叠回它逻辑上所属的原提交；独立的新功能或修复仍可单独提交。
- 对未推送的分支，默认通过 amend 或交互式 rebase 整理本次工作的提交，不必为每次折叠另行询问。先核实发布状态和工作区状态，不覆盖用户改动，也不擅自重写本次范围之外的历史。
- 对已经推送的分支，先与用户确认允许重写的分支和提交范围，以及是否允许更新远端；确认后在该范围内整理，不重复询问已授权事项。需要更新远端时检查远端进展，并使用 `--force-with-lease`，避免覆盖他人更新。

## 文档与公开内容

- 文件和提交记录只保留最终设计、行为、必要理由及维护要求。不要记录聊天过程、用户原话、修改流水账、废弃计划或“按用户要求”等对话叙述。设计理由应让未参与讨论的维护者也能独立理解。
- 用户提供参考材料，不代表允许公开它或披露其来源。不要把私人脚本名称、本机路径、私人素材及无关的来源关系带进公开项目。
- 维护面向人类的 README：说明项目是什么、解决什么问题、如何安装使用，以及必要限制；仅保留有助于使用或参与项目的构建信息。避免堆砌实现细节，也不要把验收要求或设计细节逐条包装成宣传亮点。
- 新建项目时必须生成面向 coding agent 的 AGENTS.md。以项目实际情况、已有约定和维护者的具体要求为依据，筛选并改写本 skill 中适用的条款，形成该项目独立、明确、可执行的维护规范。不要原封不动复制本 skill，也不要仅引用它；省略不适用的个人偏好及一次性初始化步骤。区分项目共同规范与个人身份设置，不要求其他维护者冒用 XiNGRZ 的提交身份。
- AGENTS.md 应独立可读，让其他维护者的 coding agent 无需安装本 skill、访问本机文件或阅读聊天记录，也能遵循一致的维护习惯。记录当前代码结构、提交与历史整理约定、必要验证、构建发布方式和必须保持的行为；语言等选择以项目实际要求为准。
- 维护过程中同步更新 AGENTS.md。已有该文件时，结合现有约定整合适用规则，保持精简，不覆盖与本次工作无关的内容。
- 文档、UI、错误信息和代码注释的语言均遵循项目约定；许可证沿用项目已有选择或用户明确要求。

## 产品与交互

- 界面和文案服务于实际任务。避免不必要的技术参数、开关，以及没有帮助的说明；能从输入或上下文确定的信息尽量自动处理，减少填写和操作步骤。
- 控件名称、位置与作用一致，说明文字不附加意外操作。简洁不能牺牲必要信息、反馈和可用性；不为这些原则指定统一技术栈或视觉风格。

## 验证与交付

- 交付能实际运行和体验的结果，不用占位页面或局部接通代替已承诺的核心功能。需要用户体验时提供可用入口、启动方式或构建产物。
- 执行适合改动的格式化、检查和测试，同时照顾格式工具未必覆盖的可读性，例如函数之间的合理空行。
- 验证真实使用路径，明确区分本地检查、远程 CI、服务启动和业务链路实测。报告实际完成范围和仍未验证的部分，不互相替代。
- 部署设计基于目标环境的网络、代理、持久化和延迟条件，不假定本机环境等同于目标环境。具体基础设施规则留在对应项目或专用 skill 中。