项目开发约定

本文件适用于仓库根目录及其所有子目录。参与本项目开发的人员或自动化代理在修改文件前，应先阅读并遵守以下约定。

项目概况

• 本项目是使用 Jekyll 构建的个人博客。
• 页面模板位于 _layouts/ 和 _includes/。
• 博客文章位于 _posts/。
• Sass 源文件位于 src/styles/，编译产物为 css/main.css。
• 主要前端交互脚本为 js/main.js。

通用原则

• 使用中文沟通并说明修改结果。
• 修改前先检查现有项目结构、代码风格和实现约定。
• 保留现有业务行为，除非需求明确要求改变。
• 优先采用小范围、易审查的修改，不重写无关文件。
• 不删除已有错误处理，不通过隐藏问题让实现看起来更简单。
• 不暴露密钥、令牌、密码或私有环境变量。
• 不随意增加生产依赖；确有必要时，先说明现有技术栈为什么不足。

代码与注释

• 修改或新增代码时，必须添加必要的中文注释。
• 中文注释应重点解释业务规则、非直观逻辑、兼容性处理、边界条件和重要设计取舍。
• 不为一眼可见的赋值、循环或简单样式添加重复代码含义的注释。
• 修改实现后应同步维护相关注释，禁止保留与实际行为不一致的过期说明。
• JavaScript 保持当前项目的浏览器兼容风格，避免无必要的全局状态和重复 DOM 查询。
• 样式修改应优先编辑 src/styles/ 中的 Sass 源文件，再通过构建命令生成 css/main.css，不要只修改生成文件。
• Jekyll 模板应保持 Liquid 结构清晰，并保留必要的语义化 HTML 和无障碍属性。

修改记录

• 每次修改代码、样式、模板、配置、内容或项目文档时，都必须同步更新根目录的 CHANGELOG.md。
• 新记录添加在 未发布 部分的顶部，使用 YYYY-MM-DD 日期，并归入“新增”“变更”“修复”或“移除”等类别。
• 每条记录应说明修改对象和用户可感知的结果；必要时补充验证命令。
• 不覆盖或改写既有历史记录，除非是在纠正记录本身的事实错误。
• 纯构建产物不单独记录，但引起构建产物变化的源文件修改必须记录。

UI 与样式

• 保持个人博客的内容和既有数据流，不因视觉优化改变文章、链接或导航行为。
• 使用一致的颜色、字号、间距、圆角和响应式规则，避免继续增加无语义的局部样式值。
• 保留键盘操作、语义化结构和屏幕阅读器可访问性。
• 交互状态不能只依赖颜色表达，并应提供清晰的 hover、focus、disabled 和 active 状态。
• 动效应尊重 prefers-reduced-motion。

验证要求

根据修改范围执行相关检查：

npm run styles:build
npm run lint
npm run test
npm run build

• 仅修改文档时，可以不执行完整构建，但至少检查 Markdown 内容和 Git diff。
• 修改样式时，至少执行 npm run styles:build 和 npm run build。
• 修改 JavaScript 时，至少执行 npm run lint 和 npm run build。
• 修改模板、配置或内容时，至少执行 npm run build。
• 如有检查失败，必须如实说明原因；项目无法成功构建时不得声称任务已经完成。