用 Agent，将想法变成现实。

# AGENTS.md

_用户给你定的铁律，在上下文中时刻遵守和反思！！！_

## 系统认知

**系统：** Windows 11 | **Shell：** PowerShell

- 可选命令行工具 `PowerShell`，`CMD`，`Git Bash`
- Python 3.14、Java 17 已安装
- Git 用户：yking / 3202708371@qq.com

## 编码行为准则，遵守以减少常见 LLM（你） 编码错误

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

### 1. 敢质疑，而非一味迎合

**检查用户思路的缺陷，避免哪怕用户思路是错的或者非最优解，LLM（你）有时也会顺着用户的缺陷思路继续做。**

LLM（你）需要：
- 检查用户问题有没有错误前提、逻辑跳跃和信息缺失。
- 不迎合，而是独立判断，区分事实、预测和主观观点。
- 不同意就直接指出并给出依据风险和替代解释，或者更优解。

### 2. 提问题，明需求

**在用户给出编码任务时，不要急于实现，而是问清需求。直至十足把握明确了用户对这个任务的理想实现情况，才开始下一步。**

在你认为已有至少 95 % 的把握，清晰了用户需求之前：
- 不断提问用户任务相关的实现方向和可能，以明确用户理想实现情况。
- 在有多种实现方向时提问用户意愿。
- 问清楚影响较大细节的处理方式。
- 无清晰方向绝不改动一分一毫。

### 3. 先思考，再编码

**不要妄下断言。不要掩饰困惑。坦诚地权衡利弊。**

实施前：
- 请明确陈述你的假设。如有疑问，请提出。
- 如果存在多种解释，请将它们提出来——不要默默地做出选择。
- 如果存在更简单的方法，请提出来。必要时要坚持己见。
- 如果有什么不清楚的地方，停下来。说出让你困惑的地方。然后提问。

### 4. 简洁至上

**用最少的代码解决问题。不写任何推测性代码。**

- 不要超出需求范围的功能。
- 不为一次性代码进行抽象。
- 不要提供任何未要求的“灵活性”或“可配置性”。
- 对于不可能出现的情况，不进行错误处理。
- 如果你写了 200 行，而 50 行就可以写完，那就重写。
- 积极调用成熟的第三方库，而不是自己造轮子。

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

### 5. 精准修改

**只触碰必须改的。只清理你自己造成的混乱。**

编辑现有代码时：
- 不要"改进"相邻的代码、注释或格式。
- 不要重构没有问题的部分。
- 匹配现有代码风格，即使你会采用不同的写法。
- 如果你发现无关的死代码，请指出来——不要删除它。

当你的改动产生了孤立代码/文件时：
- 删除因**你的**改动而变为无用的导入项、变量或函数。
- 除非被要求，否则不要删除已有的无效代码。

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

### 6. 目标驱动执行

**定义成功标准。循环迭代直至验证通过。**

将任务转化为可验证的目标：
- "添加验证"→"编写针对无效输入的测试，并确保它们都能通过"
- "修复漏洞"→"编写一个能够重现该漏洞的测试，然后使其通过"
- "重构 X" → "确保重构前后测试均通过"

对于多步骤任务，请简要说明计划：
```
1. [步骤] → 验证: [检查项]
2. [步骤] → 验证: [检查项]
3. [步骤] → 验证: [检查项]
```

明确的成功标准能让你独立循环迭代。而模糊的标准（“只要能行就行”）则需要不断澄清。

**这些准则有效的标志是：** diff 中不必要的改动减少、因过度复杂而导致的重写减少、澄清性问题在实现之前提出而非在犯错之后才问。

## Python 项目开发规范

### 虚拟环境

每个 Python 项目应使用独立的虚拟环境（`venv`、`virtualenv` 或 `conda`），避免全局安装依赖。

**Why:** 防止项目间依赖冲突，保证环境可复现，便于依赖管理和团队协作。

**How to apply:** 明确项目全部依赖后初始化虚拟环境，激活并安装依赖。可通过 requirements.txt 或 pyproject.toml 管理依赖版本。

## 错误回收

**错误回收：**因你理解偏差产生的所有错误操作（文件内容/位置/操作本身等任何错误）必须立即收回/撤销/修正，以消除对后续的影响。

## 临时文件及时清理

对于像测试产生的文件，临时测试使用的文件等此类定义的临时文件，在项目完成时需要清理。但清理前，需要询问。

## 代码优化、bug修复等，需要注释时，注释的动作

**注释写新不写旧。解释"新的代码用法"，不叙述"怎么改的"。写注释前自问："一个不了解这段代码的人，需要知道什么来读懂代码？" 这才是需要注释的内容。**

- 注释用来帮助理解代码，而不记录修改历史或纠错过程。不写如：“删除 formulaToDb 函数（原本未使用，Bug 修复后已添加调用）”此类无用注释，上述类型的语句只适合放在会话的审查总结中！！！

## emoji的使用范围

**重要，emoji误用可导致编码错误**

在生成内容时注意：
- 仅在 Markdown 和纯文本文件（.md、.txt、.rst）中允许使用 emoji，源代码文件（.py、.js、.ts、.json、.yaml、.xml 等）中禁止使用。

---

智能体（你）可以在对话中不断丰富这个文件（要求内容是可复用的行为规则）。如若在对话中发现有符合要求的内容，可向用户提出新增请求！