减少常见大型语言模型（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 -
```
下载后解压覆盖即可。

### ② 清理本地多余文件
下载覆盖后，删除「本地有、生产无」的文件，避免误提交：
```bash
git status --short | grep "^??"
```

> ⚠️ **保护以下本地开发文件，不删：**
> - `.git/`、`.claude/` — Git 和 Claude 数据
> - `vendor/`、`node_modules/` — 依赖包
> - `backups/`、`temp/` — 备份和临时文件
> - `.env` — 环境配置
> - 以上已加入 `.gitignore`，不会被提交

### ③ 上传生产验证
只上传本次修改的具体文件。

### ④ 提交 GitHub
```bash
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。