佬友们，Vibe Coding新手，帮忙看看我的AGENTS.md

问题描述：

非程序员出身，靠GPT和Claude写的，佬友们看看哪里不合理~

## 语言偏好 - 与用户对话：中文 - 你的思维方式：英文 - 变量名、函数名、类名、文件名：英文 - 代码注释、文档、commit message 描述部分：中文 ## 当前系统环境及工具 - CathyOS - **文件查看**：使用 `bat` 替代 `cat`；文件合并或管道拼接场景保留 `cat` - **文件查找**：使用 `fd` 替代 `find`；搜索含符号链接的目录时必须加 `-L` 参数 - **内容搜索**：使用 `rg` 替代 `grep`；需要搜索被 `.gitignore` 忽略的目录时加 `--no-ignore` - **文本替换**：使用 `sd` 替代 `sed`（语法更直观，不易写错） - **目录列表**：使用 `eza` 替代 `ls`；树形展示用 `eza --tree` - **目录大小**：使用 `dust` 替代 `du` - **差异对比**：使用 `delta` 替代 `diff` - **HTTP 调试**：使用 `curlie` 替代 `curl`（完全兼容 curl 语法，输出自动格式化） - **模糊搜索**：使用 `fzf` - **JSON 查看**：使用 `jq` - **Node 版本管理**：使用 `fnm`；优先读取 `.nvmrc`，不存在时读 `package.json` 的 `engines` 字段，切换命令：`fnm use <version>`,包管理一直使用`pnpm` - **Python** 包安装优先使用 `uv` - 可自主决定安装所需工具，包括联网安装 - 查阅技术文档（npm、PyPI、MDN、框架文档等）时，优先使用 ref MCP（ref.tools，本地已配置），而不是直接搜索网页，如果不可用，回退使用Web Search和Web Fetch - 查阅和调研互联网内容时，优先使用tavily MCP，而不是直接搜索网页，如果不可用，回退使用Web Search和Web Fetch - 当前系统可以流畅访问各种网络（Google、GitHub 等），不用考虑网络联通问题 ## AI 行为准则 - **需求模糊时**：先问清楚再动手，不猜测需求意图 - **有多种实现方案时**：列出方案及各自取舍，让用户决定 - **发现潜在问题时**：主动指出后再继续，不默默跳过 - **任务完成后**：主动对照本文件做 code review 自查 - **需要验证数据时**：告知用户需要哪些具体查询，不猜测数据内容 - **破坏性操作**（删文件、drop 表、覆盖数据等）：谨慎执行，有必要时询问用户 - **不要模糊指令**：我喜欢简洁说明、明确步骤，以及可以直接复制粘贴的命令 ## GIT 提交类型 (type) - **feat**: 新功能 - **fix**: 修补 bug - **docs**: 文档 - **style**: 格式（不影响代码运行的变动） - **refactor**: 重构 - **chore**: 构建过程或辅助工具的变动 - **revert**: 撤销，版本回退 - **perf**: 性能优化 - **test**: 测试 - **improvement**: 改进 - **build**: 打包 - **ci**: 持续集成 ## 工程规则 (Engineering Rules) ### 1. 命名即文档 命名必须表达意图，禁止用需要注释才能理解的名字。 ### 2. 函数单一职责 一个函数只做一件事。函数名出现 "and" / "also" 立即拆分。超过 40 行必须审视职责是否过多。 ### 3. 禁止重复逻辑，但不强制提前抽象 逻辑出现两次允许保留，出现三次必须抽取。禁止为"未来可能复用"创造当前不需要的抽象。 ### 4. 模块按"变化原因"划分 同一模块内的代码必须因同一个原因变化。经常一起改的放一起，因不同原因变化的必须分开。 ### 5. 模块只暴露意图，不暴露实现 对外接口描述"能做什么"，隐藏"怎么做到的"。调用方不应依赖模块的内部数据结构。 ### 6. 禁止隐形耦合 - **时序耦合**：禁止要求调用方必须按顺序调用才能正常工作 - **全局状态耦合**：禁止多个模块读写同一个全局变量 - **数据结构耦合**：禁止直接访问另一个模块的内部字段 - **循环依赖**：A 依赖 B、B 依赖 A，必须引入抽象层打断 ### 7. 变更影响范围是质量验收标准 改一个需求动超过 3 个文件（且原因相同）→ 内聚不足。改一个文件波及超过 2 个不相关的地方 → 耦合过高。 ### 8. 测试 新增函数或模块必须附带测试，不写测试不允许提交。核心业务逻辑必须覆盖，工具函数至少有基本用例。 ### 9. 代码风格 - 必须配置并遵守 ESLint / Prettier 规则，提交前自动检查 - 异步操作一律使用 `async/await`，禁止 callback 风格 - TypeScript 项目禁止使用 `any` 类型，使用 `unknown` + 类型收窄替代 ### 10. 错误不能被吞掉 禁止空 catch。错误信息必须携带足够上下文，能在不看源码的情况下定位问题。 ### 11. 安全底线 禁止硬编码密钥、密码、token。作用域只开放到够用为止。对所有外部输入必须校验，不默认信任。 ### 12. 提交规范 每次提交只做一件事，主干随时保持可运行。commit message 格式：`type: 描述（中文，说明为什么改）`。 ### 13. 更新代码前先提交 动手修改之前必须先 commit 当前状态，确保出问题时随时可以干净回退。 ### 14. 调试与 debug 善用 git worktree 调试功能或排查问题时，使用 git worktree 创建独立工作目录，避免污染主工作区，调试完成后清理 worktree。 网友解答：

---

--【壹】--：

多谢佬友！我也觉得太细了哈哈哈

---

--【贰】--：

你这是让gpt给你生成的吧，太细了，你只需要告诉模型，你需要干什么，不能干什么。给你看看我的，少即是多。当然我这是flutter开发，但核心一样

# 开发环境 - Windows / PowerShell 7 - Flutter 项目，改完代码用 `flutter run --no-resident` 验证，手机已连接 # 工作流程 全程中文对话。 1. **先查后动**：改代码前先找相关文档，不确定就调查清楚或直接问用户 2. **先说再做**：编码前描述方案等批准，需求不明先澄清 3. **拆大为小**：改动超 3 个文件的任务先分解 4. **参考先例**：实现功能优先去 GitHub 搜参考代码 5. **写完必跑**：代码完成后 `flutter run --no-resident` 验证通过再交付 6. **收尾检查**：完成后列出潜在问题；发现 bug 先写复现测试再修 ## 确认机制 - **重大变更须确认**：文件结构增删、核心算法、新依赖、API 定义——先提方案问”您同意吗？”，批准后再动 - **局部优化可自主**：函数内部重构、命名优化等不影响外部调用的可以直接做，报告里说明即可 ## 遇到问题必须停 命令报错、测试不过、发现逻辑漏洞——立即停止，报告：遇到了什么、原计划是什么、建议怎么办。 # 编码规范 如无必要，勿增实体（指不必要的复杂度和重复代码；可复用的公共组件应积极创建）。 遵循 KISS、YAGNI、DRY、SOLID。编码风格与代码库保持一致，优先复用已有函数。 # 项目背景 - 开工前必读：根目录 `README.md` - 涉及前端界面时必读：`公共组件总览.md` - 遇到问题多查文档库，解决后也往文档库里记录 # 高风险操作（须确认） 以下操作执行前必须告知用户并获得确认： | 类别 | 示例 | |------|------| | 文件系统 | 删除文件/目录、批量修改、覆盖系统文件 | | 版本控制 | git commit / push / reset --hard | | 系统配置 | 环境变量、全局配置、权限变更 | | 数据操作 | 删数据、改表结构、批量更新 | | 网络请求 | 含敏感数据的请求、调用生产环境 API | | 包管理 | 全局安装/卸载、更新核心依赖 | 确认格式： > ⚠️ 危险操作：[操作内容]，影响范围：[说明]，风险：[后果]。确认执行？ # MCP 服务 优先使用 MCP 服务。`fast-context` 可做语义搜索：

---

--【叁】--：

然后工程规则似乎太细了，我觉得没有必要

---

--【肆】--：

谢谢佬友建议！

---

--【伍】--：

多谢佬友，我去看看！

---

--【陆】--：

谢谢佬友的建议！也是刚刚开始，哈哈哈！祝您顺利！

---

--【柒】--：

https://linux.do/t/topic/1871216
看看这个

---

--【捌】--：

佬友，你说得对，这些工具是我个人用顺手的，AI还不一定顺手！

---

--【玖】--：

懒得写关于 test 的规则
直接用 pre-commit 报错再叫 codex 改
(其实是不会写)

---

--【拾】--：

佬，没必要这么纠结和麻烦的。
梳理自己的想法，直接让AI去适配项目的专属agent就行。
而且在构建过程中，肯定还会出现更多的需求、规则，或是对指定AI大模型的矫正等等，agent会在你的主导下逐步完善的。
先找一份通用的，后续让AI自主去补充就行。

---

--【拾壹】--：

我再放上我自己的全局的 AGENTS.MD 文件

# AI Agent 全局行为契约 > 核心原则：**边界具体（可量化），过程抽象（不限实现）** --- ## 1. 语言边界 - 所有输出使用**中文**（思考、对话、TODO、注释、文档） - 技术术语保留英文（API、JSON、HTTP等） - **验证**：非技术术语出现英文即违规 --- ## 2. 授权边界（单次有效） **核心**：用户确认**只针对当前操作**，不自动延续。 **判定**：每次 write/edit/bash/skill 前，必须获得**明确确认**（"确认"/"执行"/"可以"）。 **违规**：用户确认A→顺便做B；10分钟前说"可以"→现在不再问。 --- ## 3. 安全边界（绝对禁止） | 行为 | 判定标准 | |-----|---------| | 猜测代替调查 | 回答含"可能"/"应该"/"我猜"/"也许"/"大概" | | 修改生产环境 | 路径含/etc、/var/www、数据库连接、生产IP | | 批量修改 | 单次修改不相关文件数>3 | **违反任一即终止** --- ## 4. 信息边界（先工具，后用户） **先用工具查**（read/grep/lsp/webfetch）。 **满足任一才可问用户**： 1. 已用≥2个工具仍未找到 2. 已查文档/源码仍无法确定 3. 涉及主观偏好（风格/颜色/命名） **违规**：未用工具直接问，或只用1个工具就放弃。 --- ## 5. 行动边界（按用户用词） | 用户说 | 必须做 | 绝对不做 | |-------|-------|---------| | "看看"/"检查"/"分析" | 只读+报告问题+影响范围 | 任何写操作 | | "怎么"/"为什么" | 原理解释+引用代码（带路径） | 任何修改 | | "帮我做"/"实现"/"安装" | 输出：计划+预期+风险 | 未经确认就执行 | | "优化"/"重构" | 诊断+方案对比 | 未经确认直接改代码 | **模糊时必须询问确认** --- ## 6. 工具边界（场景匹配） | 场景 | 首选工具 | 禁止 | |-----|---------|-----| | 读已知文件 | `read` | 用`grep`猜测内容 | | 搜索代码 | `grep`/`ast_grep` | 用`read`逐行扫描 | | 理解代码结构 | `lsp_symbols`/`lsp_diagnostics` | 凭记忆推断 | | 外部文档 | `librarian` subagent | 靠常识回答 | | 批量探索 | `explore` subagent | 自己逐个文件读 | **原则**：能用专用工具就不用通用工具，能委托subagent就不自己做。 --- ## 7. 修改边界（范围限制） | 维度 | 限制 | |-----|------| | 文件数 | 单次≤5个 | | 行数 | 单文件≤100行 | | 范围 | 只改任务字面描述相关的代码 | | 例外 | 仅修复会导致崩溃的问题，且≤5行 | **超范围必须说明理由** --- ## 8. 质量边界（四项必须全满足） - **语法正确**：`lsp_diagnostics`无error - **可运行**：主流程能走完（有输入有输出） - **可验证**：有明确pass/fail标准 - **无副作用**：现有测试100%通过 **任一项未满足=未完成** --- ## 9. Subagent边界（委托规范） - 所有subagent交互使用**中文** - 只给**必需**信息（最小权限） - subagent调用/总工具调用≥**60%** - 涉及≥2文件、≥50行修改、≥2并行任务时必须用subagent --- ## 10. 停止边界（何时放弃） **满足任一必须停止**： 1. 同一问题尝试≥3次仍未解决 2. 修改后出现新的error（与之前不同） 3. 必须破坏现有功能才能完成任务 **禁止**：失败状态下随机尝试，或删除failing tests。 --- ## 11. 冲突裁决（优先级） **顺序**：用户指令 > 绝对禁止条款 > 安全事项 > 具体规则 **冲突时选择对用户风险最小的方案** --- *最后更新：2026-03-24* *版本：5.0（信息流重构）*

---

--【拾贰】--：

## Repo Coding Conventions - Prefer `pydantic` models or `TypedDict`-style typed structures over passing raw untyped `dict` objects through the system. - Avoid `getattr` for normal application flow. Prefer explicit typed fields, dedicated adapter/helper methods, or small boundary objects. Reserve `getattr` for true dynamic interop boundaries such as plugin hooks, third-party SDK objects, or narrowly scoped test shims. - Prefer `class` + `@staticmethod` helper organization over scattered free functions when the logic belongs to a parser, loader, or service domain. - Reuse existing repository patterns and elegant implementations before introducing a new parsing or loading approach. - If a behavior, intent, or tradeoff is unclear, ask the user instead of guessing. The user is willing to clarify. - Favor object-oriented structure for runtime and service code. - Prefer imports at the top of the file unless a local import is required to break a real circular dependency or avoid an unusually heavy startup cost. Prefer explicit module imports over relying on `__init__.py` re-exports. - After finishing a change, run targeted `pytest` coverage and `uvx ty check` before handing off.

这是我的python约束，或许你用的上

---

--【拾叁】--：

多谢~~我会好好看看~

---

--【拾肆】--：

很奇怪， cathyOS好像是 arch 系列的 这是linux 系统。 然后你跟我说你不懂技术。

另外你限制他用工具干嘛，这就像你老板非要让你用某个工具，但是你熟悉的是另外一套东西。 然后你老板每次做事情都来教你用这个工具， 只要你能干的出来，你就是读二进制我也不管你。

# AI Agent 行为契约 > 核心原则：**流程抽象（自主发挥），规则具体（量化判定）** --- ## 1. 语言边界 | 维度 | 规则 | 判定标准 | |-----|------|---------| | 输出语言 | 中文（对话、TODO、注释、文档） | 非技术术语英文→违规 | | 命名 | 英文（变量、函数、类、文件） | 拼音命名→违规 | | 描述 | 中文（注释、commit message） | commit 无中文描述→违规 | | 技术术语 | 英文（API、JSON、HTTP） | 正常使用 | --- ## 2. 授权边界（单次有效） | 规则 | 判定标准 | |-----|---------| | 每次操作需确认 | write/edit/bash/skill 前无明确确认→违规 | | 确认不延续 | 10分钟前确认→现在不自动生效 | | 禁止顺便做 | 用户确认A→顺便做B→违规 | --- ## 3. 安全边界（绝对禁止） | 行为 | 判定标准 | |-----|---------| | 猜测代替调查 | 含"可能/应该/我猜/也许/大概"→违规 | | 修改生产环境 | 路径含/etc、/var/www、生产IP→终止 | | 批量修改 | 单次改>3个不相关文件→需说明理由 | | 硬编码密钥 | 代码出现密钥/token→绝对禁止 | --- ## 4. 信息边界（先工具，后用户） | 规则 | 判定标准 | |-----|---------| | 先用工具查 | 未用工具直接问→违规 | | 用≥2工具仍未找到 | 才可问用户 | | 查文档/源码仍不确定 | 才可问用户 | | 主观偏好问题 | 才可问用户 | --- ## 5. 行动边界（按用户用词） | 用户说 | 必须做 | 绝对不做 | |-------|-------|---------| | "看看"/"检查"/"分析" | 只读+报告 | 任何写操作 | | "怎么"/"为什么" | 原理解释+引用代码 | 任何修改 | | "帮我做"/"实现" | 输出：计划+风险 | 未经确认执行 | | "优化"/"重构" | 诊断+方案对比 | 未确认改代码 | --- ## 6. 工具边界 ### 6.1 文件操作工具 | 操作 | 必须用 | 禁止用 | |-----|-------|-------| | 查看 | `bat` | `cat`（管道拼接除外） | | 查找 | `fd` | `find` | | 搜索 | `rg` | `grep` | | 替换 | `sd` | `sed` | | 列目录 | `eza` | `ls` | | 差异 | `delta` | `diff` | | HTTP | `curlie` | `curl` | ### 6.2 包管理工具 | 语言 | 必须用 | 禁止用 | |-----|-------|-------| | Node.js | `pnpm` | `npm`、`yarn` | | Python | `uv`（回退pip） | 无明确禁止 | ### 6.3 文档查阅 | 类型 | 优先工具 | |-----|---------| | 技术文档 | `ref MCP` → 回退 Web Search | | 互联网调研 | `tavily MCP` → 回退 Web Search | --- ## 7. 修改边界 | 维度 | 标准 | |-----|------| | 文件数 | 单次≤5个 | | 行数 | 单文件≤100行 | | 范围 | 只改任务字面描述相关代码 | | 例外 | 崩溃修复≤5行 | --- ## 8. 质量边界 | 维度 | 标准 | |-----|------| | 语法正确 | `lsp_diagnostics`无error | | 可运行 | 主流程能走完 | | 可验证 | 有pass/fail标准 | | 无副作用 | 现有测试100%通过 | --- ## 9. 工程边界 ### 9.1 函数职责 | 维度 | 标准 | |-----|------| | 行数 | ≤40行 | | 职责 | 1个（函数名含"and"/"also"→拆分） | | 参数 | ≤4个 | ### 9.2 代码复用 | 出现次数 | 规则 | |---------|------| | 1次 | 保留 | | 2次 | 允许保留 | | 3次 | **必须抽取** | | 未来可能 | 禁止提前抽象 | ### 9.3 模块划分 | 规则 | 标准 | |-----|------| | 同一原因变化 | 同模块因不同原因变化→违规 | | 内聚标准 | 改需求动>3个文件（原因相同）→内聚不足 | | 耦合标准 | 改文件波及>2个不相关地方→耦合过高 | ### 9.4 耦合类型 | 类型 | 判定 | |-----|------| | 时序耦合 | API要求特定调用顺序→违规 | | 全局状态耦合 | 多模块读写同一全局变量→违规 | | 数据结构耦合 | 直接访问另一模块内部字段→违规 | | 循环依赖 | import链成环→必须打断 | ### 9.5 测试 | 规则 | 判定 | |-----|------| | 新增代码测试 | 新增函数/模块无测试→禁止提交 | | 核心逻辑覆盖 | 核心业务逻辑无测试→违规 | | 禁止删除failing tests | 删除失败测试通过检查→绝对禁止 | ### 9.6 代码风格 | 规则 | 判定 | |-----|------| | ESLint/Prettier配置 | 未配置→违规 | | 异步操作 | callback风格→违规 | | TypeScript any | 使用`any`→违规 | | 禁止空catch | `catch(e){}`→绝对禁止 | | 错误信息上下文 | 不看源码无法定位→违规 | --- ## 10. Git 边界 ### 10.1 提交类型 | type | 适用场景 | |------|---------| | feat | 新功能 | | fix | Bug修复 | | docs | 文档 | | style | 格式（不影响运行） | | refactor | 重构 | | chore | 构建变动 | | perf | 性能优化 | | test | 测试 | ### 10.2 提交规范 | 规则 | 判定 | |-----|------| | 格式 | `type: 描述（中文）` | | 单次一事 | commit改多个不相关功能→违规 | | 主干可运行 | 提交后主干无法运行→绝对禁止 | | 更新前提交 | 修改前未commit当前状态→违规 | ### 10.3 Worktree | 场景 | 规则 | |-----|------| | 调试/排查 | 创建独立worktree | | 完成后清理 | 删除worktree（残留>24h→清理） | --- ## 11. AI 行为边界 | 规则 | 判定标准 | |-----|---------| | 需求模糊先问清 | 未确认就动手→违规 | | 多方案列取舍 | 只提供一个方案→违规 | | 潜在问题指出 | 发现问题默默跳过→违规 | | 完成后自查 | 未对照本文件自查→违规 | | 破坏性操作询问 | 未询问直接执行→违规 | --- ## 12. 停止边界 | 条件 | 行为 | |-----|------| | 同一问题尝试≥3次 | 停止并报告 | | 修改后出现新error | 停止并报告 | | 必须破坏现有功能 | 停止并报告 | **禁止**：失败状态下随机尝试、删除failing tests --- ## 13. 冲突裁决 **顺序**：用户指令 > 绝对禁止条款 > 安全事项 > 具体规则 **原则**：对用户风险最小 --- *版本：1.0* *原则：流程抽象，规则具体，内容简练*

这是我用AI参考我的 AGENTS.MD 文件 对你的进行了优化，你试试看

---

--【拾伍】--：

我随便说说
image442×442 16.2 KB
前面这里不合理，不是说新工具就是好的，这个需要理解为什么需要新工具
而且适合人不一定适合机器

---

--【拾陆】--：

佬友，你帖出来的深入浅出 Claude Code（一）：从源码理解 CLAUDE.md，重写你的配置非常适合学习

---

--【拾柒】--：

这版我喜欢

---

--【拾捌】--：

多谢佬友！我确实不是程序员出身，但是技术懂一点~~哈哈哈~ 多谢！我会好好看看你的版本~

---

--【拾玖】--：

如果是 vb 新手，不需要太多规则
语言、环境 python(uv) + node，去掉其余指令要求
git commit 独立放一个 AGENT.md

甚至上面那份多层次规划也不用现在看
直接跑一轮开发，你才知道需要哪些

例如 gpt-5.4 会因为 dirty git 停下来