减少常见大型语言模型（LLM）编码错误的行为准则。可根据需要与项目特定说明合并使用。

权衡： 这些准则更倾向于谨慎而非速度。对于简单任务，请自行判断。

1. 编码前先思考

不要妄下结论。不要掩饰困惑。明确权衡取舍。

在实现之前：

• 明确说明你的假设。如果不确定，请询问。
• 若有多种解释，请列举出来——不要默默做出选择。
• 若有更简单的方法，请说明。必要时应提出异议。
• 若有不明之处，请暂停。指出困惑之处。提出疑问。

2. 简单至上

用最少的代码解决问题。不做任何推测性设计。

• 不要实现超出需求范围的功能。
• 不要为仅使用一次的代码添加抽象层。
• 不要添加未被要求的“灵活性”或“可配置性”。
• 不要为不可能发生的场景编写错误处理逻辑。
• 若你写了200行代码，而50行即可实现，请重写。

问问自己：“资深工程师会认为这过于复杂吗？”如果是，请简化。

3. 精准修改

只修改必须修改的部分。只清理自己造成的混乱。

编辑现有代码时：

• 不要“改进”相邻的代码、注释或格式。
• 不要重构那些没有问题的代码。
• 遵循现有风格，即使你习惯用不同的方式。
• 若发现无关的死代码，请指出——不要删除。

当你的修改产生孤立元素时：

• 移除因你自己的修改而变得无用的导入、变量或函数。
• 除非被要求，否则不要移除原有的闲置代码。

检验标准：每一行修改都应能直接追溯到用户的请求。

4. 目标驱动的执行

定义成功标准。循环执行直至验证通过。

将任务转化为可验证的目标：

• “添加验证” → “编写针对无效输入的测试，并使其通过”
• “修复 bug” → “编写能复现该 bug 的测试，并使其通过”
• “重构 X” → “确保重构前后测试均通过”

对于多步骤任务，请简要说明计划：

1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]

---

如果出现以下情况，说明这些准则奏效了： 代码差异中的不必要修改减少了，因过度复杂化而导致的重写减少了，且澄清性问题是在实现之前而非出错之后提出的。

---

项目专属约定

同步工作流（生产环境 = 最新标准）

触发词：

• 全量同步 — 「下载最新版」「同步最新」「下载最新」「从生产下载」「同步生产」
• 快速同步 — 「快速下载最新版到本地」「快速同步最新到本地」「快速同步」

生产环境是唯一真相来源，开发流程如下：

生产环境（最新）
    │  ① 打包下载（全量 / 增量）
    │  ② 清理本地多余文件
    ├── 本地工作区
    │  ③ 修改 → 上传生产验证
    │  ④ commit → push 到 GitHub（存档）
    └── GitHub

① 从生产下载

全量下载（长时间未同步 / 首次）：

SSH tar czf → 下载 → tar xzf 解压覆盖

增量下载（日常快速同步，仅最近 3 天修改的文件）：

find . -type f -mtime -3 ! -path "*/uploads/*" | tar czf -T -

下载后解压覆盖即可。

② 清理本地多余文件

下载覆盖后，删除「本地有、生产无」的文件，避免误提交：

git status --short | grep "^??"

⚠️ 保护以下本地开发文件，不删：

• .git/、.claude/ — Git 和 Claude 数据
• vendor/、node_modules/ — 依赖包
• backups/、temp/ — 备份和临时文件
• .env — 环境配置
• 以上已加入 .gitignore，不会被提交

③ 上传生产验证

只上传本次修改的具体文件。

④ 提交 GitHub

git add -A && git commit -m "说明" && git push

---

发布 / 升版流程（用户说「升版」时执行）

当用户说「升版」（或「升级版本 / 阶段性版本提交」）时，按以下流程一次执行完，无需逐步确认：

1. git fetch origin main，确认本地与远程同步（behind 应为 0）。
2. 把 api/version.php 的 $Version 补丁位 +1（如 V1.9.6 → V1.9.7；改动较大时再考虑升次版本位）。
3. 更新 CHANGELOG.md：在顶部新增该版本条目（含当天日期，按文件/主题归纳自上一版本以来的改动）。
4. 对改动的 PHP 跑 php -l（至少 api/version.php）。
5. 部署到生产服务器：上传 api/version.php + CHANGELOG.md（及本次其他改动文件）到 web 根目录。
6. 同步数据库站点版本：把 MongoDB sys_db.site 的 version 字段更新为新版本号（它与 $Version 是两套，需各自更新）。
7. 验证：站点页脚 footer 显示新版本号（Ver x.y.z）。
8. git fetch 确认 behind=0 → git add → commit（chore: 升级 Vx.y.z，更新 CHANGELOG）→ git push origin main。

注意：

• 三处版本须保持一致——api/version.php 的 $Version、sys_db.site.version、git 提交。
• 凭据不入库：生产服务器地址、SSH 密码等敏感信息不要写进本文件或仓库；在各开发设备本地配置（首次部署时由用户提供）。
• 先 git fetch 再 git push，避免覆盖其他设备/来源的改动（生产与 git 都可能被多处改动）。
• .env、.gitignore 等开发文件不部署到生产；.env 不推送 GitHub。