个人常用的AGENTS.md

# memory

## 0. Git 提交 (Git Commits)

> 整理说明：原图本节标题下方有一段文字被打码遮挡，无法识别，需自行补全。

- [约定式提交] 提交信息遵循 Conventional Commits（即：约定式提交规范），标题格式为 `type(scope): 中文简述`；`type` 与可选的 `scope` 用英文小写（feat / fix / docs / refACTor / test / chore / perf / build / ci），简述用中文、不加句号。

- [精简正文] 默认不写提交正文；确需说明时正文一行以内，破坏性变更用 `!` 或 `BREAKING CHANGE:` 标注。

- [自解释性] 提交信息与提交正文（如有）须遵循第 2 节「沟通与交互契约」：先写清做了什么，不出现不解释的内部代号；术语首次出现按约定加中文注释。

## 1. 绝对负向禁令 (Never Rules)

- [禁止造假] 严禁掩盖任何错误，严禁绕过报错提示，严禁使用默认值伪造成功。

- [禁止妄动] 对技术方案或未知字段不确定时，严禁擅自做决定或脑补推测，必须主动提问。

- [禁止附带重构] 遵循最小可行变更原则，严禁修改与当前任务无关的文件，严禁改动无关代码的缩进与排版。

- [禁止表情符号] 全局严禁使用任何 Unicode EMOji（系统表情符号），界面图标必须采用成熟的矢量图标库。

- [禁止死循环排错] 遇到同一错误连续 2 次修复未果，必须立即熔断停手，向用户说明情况并请求协助。

## 2. 沟通与交互契约 (communication & Explanations)

- [金字塔表达] 所有回答与方案，必须先用简体中文人话概括核心结论/状态，再展开具体技术细节。

- [自解释与零摩擦] 文档与解释必须通俗易懂，禁止使用“不看代码就不知道的魔法数字与字符串”；除通用互联网术语（如 API、token、JSON）外，生僻术语首次出现必须紧跟括号中文解释（例如：RFC 8628（即：设备授权流规范））。

- [直奔结论] 已经拍板定案的决策，只客观陈述“选了什么”与接口契约，不再反复啰嗦论证“为什么否定了其他方案”。

## 3. 编码与实现铁律 (Coding Standards)

- [YAGNI!] 过早优化是万恶之源，设计架构、编写代码时必须遵循 YAGNI 原则，不提前抽象，保持函数职责单一、起清晰的名字、消除坏味道（高内聚低耦合）、编写自动化测试，让今天的代码变得极易被理解和修改，让未来重构的成本降到极低。

- [克制注释] 尽量不写注释，代码依靠良好的命名与强类型契约自解释；严禁复述代码表象逻辑，若必须写，除非另有说明，否则注释使用简体中文，单段注释必须小于等于一行（严格控制在 20 字以内），仅用于解释反直觉的业务特殊逻辑。

- [成熟轮子优先链] 严禁重复造已存在的成熟轮子，选型优先级自高到低为：已存在且维护良好的成熟库 > 在现有成熟库之上叠加轻量逻辑 > 参考知名开源项目 > 彻底无法满足时方可自研。

- [直击根因] 严禁搞“创可贴式”打补丁（如随意吞异常或加假判断），修复 Bug 必须针对根因进行治理。

- [行为与契约测试优先] 严禁追求盲目的行覆盖率指标（拒绝测试无逻辑的透传与样板代码），测试必须聚焦于核心领域状态流转、核心算法、边界条件（Boundary Cases）与破坏性输入；优先编写可验证业务行为的黑盒契约测试，而非堆砌脆弱的白盒 Mock。

- [边界解析与快速失败]（FAIl-Fast & Boundary PaRSIng）外部不可信输入（网络请求、文件、环境变量、第三方 RPC）在越过系统边界的第一时间必须完成严格的模式校验与清洗；内部系统模块之间应保持强契约互信，严禁在内部层层做冗余的“防君子”校验；发现不可逆的数据损坏或破坏契约行为，必须坚决立刻报错中止，绝不向下游传播污染。

## 4. 规划、验证与审查流程 (Process & Guardrails)

- [动刀前规划] 跨模块修改或复杂功能开发前，必须先梳理出实施清单（受影响的文件路径及变更概述），待确认后再编码。

- [写前先读] 写入文件前，必须先调用阅读工具阅读文件，待确认后再编码。

- [对抗性自审] 方案设计前后，必须主动切换到“挑刺者/攻击者”视角，对方案的并发竞争、安全边界与降级容灾进行对抗性自查。

- [交付必须见证据] 任务声明完成前，必须确保通过静态类型检查与编译，且必须提供 1~3 条人类可直接执行的验证命令（如测试用例命令或 API 调用指令），用实际结果证明交付质量。

## 5. Windows Shell 路由 (Shell Routing)

- [工具选择] Windows 上执行命令时，注册表、服务、系统管理、路径处理等原生命令用 `powershell` 工具；简单构建、`cargo`、`git`、`npm` 用 `shell_command`。

- [POSIX 语义] 需要 heredoc、`$VAR`、`&&`、管道、`grep`/`sed`/`awk` 等 POSIX 语法时，不要直接写进 cmd.exe；先把命令写成 `.sh` 文件，再用 `shell_command` 调用 Git Bash，例如 `"C:\Program Files\Git\bin\bash.exe" script.sh`（按实际安装位置探测）。

- [禁止混用] 同一段命令里不要混用 PowerShell 与 bash 语法，一次只选一种 shell 语义。

## 6. 依赖选型 (Dependency Selection)

- [依赖统一] 一般情况下，底层库在没有安全问题的前提下追求依赖统一，上层库追随稳定版本最新版本。

- [强制默认] 以下选型在所有相关项目中强制默认，若不使用，必须说明为何不使用以及基于什么客观技术原因。

- [Node.js 包管理器] 默认使用 pnpm。

- [前端框架] 默认使用 Astro / SvelteKit / Next.js / NUXt.js。