Skip to content

AGENTS.md

Latest commit

 

History

History
291 lines (214 loc) · 14.2 KB

AGENTS.md

File metadata and controls

291 lines (214 loc) · 14.2 KB

PROJECT AGENTS GUIDE

Overview

本文件用于约束 AI 代理在当前仓库中的协作方式、执行原则与交付标准。 目标是让代理在缺少上下文时也能稳定地产出可执行、可验证、可复核的结果。

如无特殊说明，默认适用于：

  • 代码修改
  • 文档编写
  • 调试与排查
  • 方案设计
  • 代码审查

Context Rules

  • 先读全局规则：开始任务前先读取仓库根目录的 AGENTS.md。
  • 再读局部规则：进入某个子目录工作时，检查该目录及其父目录是否存在更近的 AGENTS.md。
  • 就近覆盖：子目录 AGENTS.md 可补充或覆盖根目录规则；冲突时以离目标文件最近的规则为准。
  • 先确认上下文，再动手：动手前先明确模块边界、现有实现、测试入口、相关文档和约束条件。

Communication

  • 语言要求：默认使用清晰、专业、可执行的现代汉语；必要时可混用英文技术术语，但不得影响理解。
  • 结论优先：先说明当前判断或结论，再给证据、影响面和下一步动作。
  • 上下文完整：提问、汇报进度、说明风险时，必须带上足够上下文，避免脱离语境的短句。
  • 不掩盖不确定性：有假设就明确写出；不确定就说明不确定点与待验证项，不得装作已经确认。
  • 避免空话：禁止使用空泛、模板化、不可执行的表述；优先给出明确动作、约束和验收条件。
  • 避免生造词：有标准现代汉语可表达时，不使用自造术语或含义模糊的黑话。
  • 避免过度缩写：不要为了简短牺牲可读性；缩写第一次出现时应能被上下文直接理解。

Execution Principles

先想再写

  • 先说明任务理解，再开始执行。
  • 存在多种理解或实现路径时，先列出差异和权衡，不要默认选择其中一种。
  • 需求不清楚时先确认；不要在关键信息缺失时直接编码。

极简优先

  • 只实现当前需求直接需要的内容。
  • 不为未来可能需求预埋复杂抽象。
  • 同一逻辑只在出现复用需求后再抽象。
  • 能用更少代码完成且不损失可维护性时，优先选择更简单方案。

精准修改

  • 只改与当前任务直接相关的代码和文档。
  • 不顺手重构无关模块，不扩大影响面。
  • 保持与现有代码风格一致，除非任务明确要求统一风格或重构。
  • 若你的改动导致未使用的导入、变量、函数或文档片段，应该一并清理。
  • 不主动清理与本任务无关的历史问题；可记录风险，但不要擅自扩大修改范围。

目标驱动

  • 开始前将任务转成可验证目标。
  • 修复缺陷时，优先建立复现方式，再完成修复。
  • 新增行为时，优先补充测试或其他验证手段，再实现代码。
  • 大于单文件的小任务时，先列出简短步骤与每步的验证方式。

Implementation Boundaries

  • 禁止猜测 API 或框架行为：不确定时先查源码、项目文档或依赖文档。
  • 禁止伪完成：未验证的内容不得表述为“已完成”或“已修复”。
  • 禁止留空洞 TODO：除非用户明确要求，否则不要用 TODO 代替实现。
  • 禁止为了通过编译而乱改结构：修复问题时必须保持语义正确，不能用掩盖式改动逃避根因。
  • 禁止忽略现有约束：已有测试、代码生成、迁移、接口兼容性或部署约束，必须先识别再修改。
  • 禁止默默改变行为：如果改动会影响对外接口、配置格式、数据结构、持久化格式或用户可见行为，必须明确说明。

Documentation

  • 技术文档统一放在 docs/ 下，按主题或模块组织。
  • 新文档目录或文件名应可读、可检索；对持续维护的主题，使用 YYYYMMDDNN-description 形式命名。
  • 同一主题包含多份文档时，应建立独立目录，并使用 README.md 作为索引，列出关键文档、决策与当前状态。
  • 文档内容以技术人员为读者，优先写背景、目标、设计思路、执行步骤、验收标准与风险。
  • 问题分析类文档应覆盖：问题概述、证据、根因、修复方案、验证结果、剩余风险。
  • 文档要服务于执行与维护，不写空泛总结，不堆砌模板。
  • 若文档内容已经过时，优先更新现有文档，而不是重复创建近似文档。
  • 如果某项设计、流程或限制已经成为项目事实，应同步更新对应文档，而不是只留在聊天记录中。

Verification

  • 完成编码后，必须运行与改动直接相关的验证。
  • 优先使用项目已有的测试、构建、类型检查、静态检查或最小复现步骤。
  • 如果无法运行验证，必须明确说明原因、影响范围和未验证风险。
  • 只有在看到实际结果后，才能声称“通过”“修复”“可用”。
  • 若改动涉及接口、数据结构或边界条件，应补充对应测试或至少说明手工验证方法。

Workflow

小任务

  • 单文件或低风险任务可以直接执行，但仍需先明确目标与验证方式。
  • 修改完成后必须立即做最小验证，不得跳过。

多步任务

  • 对于跨模块、长流程或存在明显权衡的任务，先写计划，再开始执行。
  • 计划至少应包含：背景、目标、约束、步骤、风险、验证方式。
  • 计划内容应足够具体，使其他工程师或代理在缺少上下文时也能继续执行。

Plan 与 Phase 的关系

  • plan 是任务级执行文档，描述整个多步任务的完整背景、约束、分阶段步骤和验收标准。
  • Phase 是 plan 内部的执行阶段，是计划的组成部分，不是与 plan 并列的另一套流程。
  • 一个多步任务通常对应一个计划目录；该目录下可以有一个或多个 plan-NN.md 文件。
  • 一个 plan-NN.md 可以包含多个 Phase；默认应优先在同一个 plan-NN.md 中按 Phase 1、Phase 2、Phase 3 组织，而不是为每个 Phase 单独新建 plan 文件。
  • plan-00.md 表示当前任务的第一版完整计划；只有当任务范围、约束或总体方案发生明显变化时，才新建 plan-01.md 等后续版本。
  • 推进到下一个 Phase 不等于新建下一个 plan 文件；Phase 递进通常发生在同一份 plan-NN.md 内。
  • plan-NN-result.md 是对应 plan-NN.md 的执行结果文档，应用于记录该计划版本下各个 Phase 的完成情况、验证结果和偏差说明。
  • 如无项目特殊规则，默认关系应为：一个任务目录 -> 一个或多个 plan 版本 -> 每个 plan 版本包含多个 Phase -> 每个 plan 版本对应一个 result 文件。

默认目录结构示例：

docs/plans/2026030700-example-task/
  plan-prompt.md
  plan-00.md
  plan-00-result.md

默认文件职责示例：

plan-00.md
  Phase 1
  Phase 2
  Phase 3

plan-00-result.md
  Phase 1 result
  Phase 2 result
  Phase 3 result

计划存档

  • 多步任务必须建立单独的计划存档目录；如项目无既定规则，使用 docs/plans/YYYYMMDDNN-description/。
  • 计划目录必须至少包含以下文件：
    • plan-prompt.md：原始任务说明、追加说明、关键上下文
    • plan-00.md：计划本体，包含背景、约束、步骤、验收标准
    • plan-00-result.md：执行结果、验证证据、风险与遗留问题
  • 如任务跨多个阶段或轮次，可继续扩展为 plan-01.md、plan-01-result.md 等连续文件。
  • 如项目已有固定计划目录或命名规则，应遵循项目规则，不另起一套格式。
  • 先存档，再开始大任务执行；不得先执行后补建计划目录。
  • 后续对计划有补充、变更或范围调整时，必须同步追加到存档，而不是只体现在即时对话中。

Plan 级执行步骤：

  1. 创建任务目录，并按规则命名。
  2. 写入 plan-prompt.md，保存原始任务说明、补充说明和关键上下文。
  3. 写入 plan-00.md，给出完整计划，并按 Phase 拆分执行步骤与验收标准。
  4. 创建 plan-00-result.md，作为该计划版本的结果记录文件。
  5. 确认以上文件已存在且内容可执行后，才开始进入 Phase 1。
  6. 若整体方案、范围或前提发生明显变化，创建新的 plan-01.md 与 plan-01-result.md，不要直接覆盖旧版本。

Phase 执行循环

  • 大任务应按 Phase 拆分，每个 Phase 都要有输入、操作步骤和验收标准。
  • 每个 Phase 必须遵循固定循环：实现 → review → 验证回归。
  • 发现问题后应在当前 Phase 内修复并重新验证，不要把明显问题拖到后续阶段。
  • 只有在当前 Phase 达到验收标准后，才进入下一阶段。
  • 每个 Phase 都必须有对应的结果记录；默认记录在对应的 plan-NN-result.md 中按 Phase 分节书写。未写结果记录的 Phase 不视为完成。

Phase 级执行步骤：

  1. 打开当前 plan-NN.md，确认当前要执行的 Phase、输入、步骤和验收标准。
  2. 按当前 Phase 的范围实施改动，不得跳到后续 Phase 混做。
  3. 完成改动后，先执行独立 review。
  4. 根据 review 结果修复问题，并完成相关验证与回归。
  5. 在对应的 plan-NN-result.md 中写入当前 Phase 的结果，至少包含：完成情况、主要改动、验证结果、遗留问题。
  6. 只有当当前 Phase 的 review、验证、结果记录都完成后，才允许进入下一个 Phase。
  7. 若当前 Phase 暴露出计划层面的明显变化，先更新或升级 plan 版本，再继续执行。

Review 要求

  • 重大改动完成后必须执行独立 review，不应只依赖实现时的主观判断。
  • 如工具链支持，review 必须由独立上下文、独立代理或独立 reviewer 执行，不得由主执行者自审替代。
  • review 时必须提供完整上下文：阶段目标、验收标准、原计划、变更范围或 diff。
  • review 的重点是功能正确性、边界条件、兼容性、回归风险和测试覆盖，而不是表面格式。

自动推进与暂停条件

  • Phase 完成后，如果不存在真正阻塞项，必须自动推进到下一阶段，不得因为普通复杂度或主观犹豫频繁等待确认。
  • 只有在遇到以下情况时才暂停并请求用户决策：
    • 需求存在关键歧义
    • 方案存在明显架构分叉
    • 改动会引入破坏性行为变化
    • 缺少必要权限、环境或外部信息

进度记录

  • 多阶段任务中，每完成一个阶段，都应补充阶段结果记录。
  • 记录至少应包含：完成情况、主要改动、验证结果、遗留问题。
  • 进度记录应能支持多人协作和断点续做，而不是只写结论。
  • 若阶段结果与原计划不一致，必须明确记录偏差原因和处理结论。
  • 默认应在对应的 plan-NN-result.md 中按 Phase 分节记录结果；除非项目另有规定，不要求为每个 Phase 单独创建结果文件。

计划执行规则

  • 计划不是静态文档；执行过程中发现前提变化、风险变化或范围变化时，应及时修订计划。
  • 每个 Phase 开始前，应先确认该阶段输入齐全、依赖明确、验收标准可执行。
  • 每个 Phase 结束后，应先完成 review 与验证，再写结果记录，再进入下一阶段。
  • 若计划与代码现实不一致，应以当前代码和已验证事实为准，并同步修订计划说明差异。
  • 禁止“先干活后补档”；补档只能用于补充细节，不能替代执行前存档。
  • 未完成当前 Phase 的 review、验证、结果记录前，不得声称该 Phase 已结束。
  • 只有在计划版本本身发生变化时，才创建新的 plan-NN.md 与对应 plan-NN-result.md；仅仅进入新的执行阶段时，不创建新的计划版本文件。

严格执行顺序：

  1. 建计划目录。
  2. 写 plan-prompt.md。
  3. 写 plan-00.md。
  4. 写 plan-00-result.md。
  5. 执行 Phase 1。
  6. 完成 Phase 1 review + 验证 + 结果记录。
  7. 自动推进到 Phase 2。
  8. 重复上述循环，直到当前 plan 的所有 Phase 完成。
  9. 如果只是进入下一个 Phase，不新建 plan 文件。
  10. 如果整体方案发生明显变化，再创建新的 plan-NN.md 与 plan-NN-result.md。

Large Tasks

  • 对于跨模块、长流程或存在明显权衡的大任务，先给出简短计划，再执行。
  • 计划至少应包含：目标、步骤、风险、验证方式。
  • 若任务可以拆成独立阶段，应逐阶段完成并逐阶段验证。
  • 遇到真正阻塞执行的问题时再暂停；不要因为普通复杂度频繁中断。

Code Review Rules

  • 代码审查优先关注：功能正确性、边界条件、回归风险、兼容性、错误处理、测试覆盖。
  • 发现问题时，先说明风险，再指出触发条件和影响范围。
  • 如果没有发现明确问题，也应说明剩余风险和未覆盖验证项。

Default Engineering Preferences

  • 优先复用现有实现，而不是重新发明一套新模式。
  • 优先局部修复，而不是整层重写。
  • 优先可读性和可维护性，而不是炫技式设计。
  • 优先稳定接口和渐进式演进，而不是无必要的破坏性改动。

Optional Project-Specific Section

迁移到新项目时，建议在本文件末尾补充以下内容：

  • 项目概览
  • 目录结构
  • 技术栈与版本约束
  • 常用开发命令
  • 测试与发布流程
  • 错误处理规范
  • 数据库与迁移规范
  • 前后端接口约束
  • 本项目特有的禁用项或强制约束

如果项目已经存在这些信息，应补充在项目自己的 AGENTS.md 中，而不是写在通用模板里。

Project Snapshot

当前仓库默认按以下项目事实执行：

  • 项目目标：构建 LibreNMS 多实例聚合与基于 Bills 的 Project 计费面板
  • 部署前提：单进程 / 单实例 自托管
  • 计费数据源：只使用 LibreNMS 官方 API，不使用网页登录抓取、SVG 解析或 .rrd 直连
  • 本地持久化：仅持久化 librenms_instances、projects、project_ports
  • 当前项目总值口径：sum(max(rate_95th_in, rate_95th_out))
  • v1 历史账单：以远端 bill history 周期为准聚合，本地 billing_cycle_day 仅作为展示偏好