adaptive-agent-development

Imported from ppstone10/adaptive-agent-development (AGENTS.md). Install upstream with npx skills add ppstone10/adaptive-agent-development. Copyright stays with the author.

自适应 Agent 开发工作流

目标

将主要时间和上下文用于理解、修改项目。始终采用足以建立信心的最轻流程，不以流程仪式替代工程判断。

每项任务的起点

1. 阅读本文件并检查当前工作树状态；保存当前本地日期和开始时间。没有现成精确时间时只读取一次系统时钟，不轮询。
2. 在加载项目文档或 Skill 前先判定任务等级。
3. 从用户报告的行为、符号、错误或边界开始精准搜索。
4. 保留用户已有改动，不让无关修改进入本次差异。

任务等级与路由

按范围、不确定性、契约与数据、可逆性、安全与隐私、运行影响和验证难度中的最高风险判级，不能按修改行数判级。证据表明风险升高时立即升级。

如果 Agent 不支持原生 Skill 加载，直接阅读对应的 .agents/skills/<name>/SKILL.md。只有首次接入、项目上下文缺失或冲突、基础结构重组时才使用 project-bootstrap。

上下文预算

• 默认不通读 README.md、DESIGN.md、ARCHITECTURE.md、LEARNING.md 和 TRACE。
• 只有安装、运行、环境或用户入口变化时才读 README 的相关章节。
• 只有目标、非目标、行为、流程或验收变化时才读 DESIGN 的相关章节。
• 只有边界、所有权、数据流、协议或不变量变化时才读 ARCHITECTURE 的相关章节。
• 只有功能级行为契约或验收需要确认时，才按关键词读取相关 spec/ 文件；禁止通读全部 Spec 或全仓追溯表。
• 按受影响关键词搜索 LEARNING 与 trace 文件名或内容；没有具体需要时禁止顺序阅读历史。
• 扩大到整个模块或仓库前，先检查入口、所有者、接口、测试和已知依赖方。
• 不询问仓库能够回答的问题。只有未解决的选择会实质改变行为、范围、风险、迁移或验收时才询问。

新内容与新方法的前置调研

• 新功能、新算法、新架构方式、新外部依赖/协议，或项目中没有成熟先例的实现方法，在确定方案前必须查阅网络上的成熟做法。
• 局部缺陷、机械修改和完全沿用项目既有模式的工作不触发网络调研。
• 优先查阅官方文档、正式标准、成熟产品技术资料和维护良好的开源实现；只提取与当前决策有关的约束、取舍和失败模式。
• 调研必须设置范围并及时停止：通常比较 2～4 个高质量来源，证据已足以选择方案后不继续扩张搜索。
• 结合本项目边界作出选择，不得未经许可证、安全、兼容性和维护成本检查就直接照搬。网络不可用时说明缺口；只有该缺口会实质改变方案时才暂停实施。

按需 Spec 驱动

• Spec 用稳定规范 ID 定义某项行为“必须是什么”，任务 TRACE 跟踪一次修改“如何演进”，DESIGN 描述项目级目标与整体行为；三者不得互相复制。
• L2 默认不创建 Spec。L3 新增或改变用户可见行为、需要跨会话验收或分阶段交付时，加载 spec-driven-change 使用轻量档。
• L4/L5 涉及公共契约、数据结构、协议、迁移、安全、隐私、权限或多客户端一致性时，加载 spec-driven-change 使用完整档；纯内部且行为不变的结构调整不为形式创建。
• Spec 的追溯表就近放在对应功能文件中，连接规范 ID、验收、测试或人工入口、实现符号与实际验证；不得默认建立需要每轮通读的全仓巨型矩阵。
• 可自动化的新行为优先保留实现前失败证据；局部缺陷、行为不变重构和无法自动化场景按比例使用回归测试、基线对比或人工验收，不为展示红灯回退现有改动。

范围纪律

• 只解决用户要求的问题和必需的协同修改。
• 优先沿用现有模式和直接局部修改，避免无必要的新抽象。
• 精准修改中不得混入大范围重构、格式化、依赖升级或相邻清理。
• 有价值但超出范围的问题应单独报告，不得静默修复。
• 除非所选流程明确要求改变，否则保持公共契约和架构不变。

触达代码清晰度

• 只检查本轮新增或实质修改的声明：名称在调用位置能否表达意图、文件是否保持单一内聚职责、函数是否混合编排/计算/副作用、相关注释是否仍然真实。
• 优先使用项目领域词汇和语言官方约定；名称应足以区分动作、对象、条件与副作用，不以最短名称为目标。
• 文件拆分按所有权、依赖方向和修改原因判断，行数只作为调查信号；注释说明用途、契约、不变量和“为什么”，不重复代码表面行为。
• 局部清晰度修正只有不扩大审查范围时才随任务完成；跨文件、公共符号或大范围整理必须升级或拆成独立任务，不得混入精准修复。
• 明确的命名、文件拆分、注释治理任务，或 L3/L4 中出现多职责和难以命名的代码时，按 full-development 指引读取代码清晰度参考。

按比例验证

• 选择能覆盖变更行为并编译受影响范围的最小检查。
• 只有影响面扩大、定向覆盖不足或仓库有强制门禁时才扩大检查。
• 更广检查成功且已覆盖更窄检查后，不重复运行后者。
• 相关代码未变化时，不重复已经成功的同等覆盖验证。
• 未运行或未通过的检查不得声称成功；必须报告实际命令、结果和重要缺口。

知识同步

实现后，根据最终变更判断是否改变了持久项目事实：

• 安装、运行或使用方式 -> README；
• 项目级目标、非目标、整体行为或用户流程 -> DESIGN；
• 功能级持久行为、验收或追溯关系 -> 对应 Spec；
• 组件、所有权、数据流、协议、数据结构或不变量 -> ARCHITECTURE；
• 非显然且可复用的项目经验 -> LEARNING；
• 复杂调查或重大变更的演进证据 -> 当天 docs/traces/YYYY-MM-DD.md 中一个稳定任务编号。

如果均未改变，不编辑文档，也不加载 sync-project-knowledge。否则加载它，并只更新事实所属文档。概述文档描述当前系统，不记录修改流水账。

最小收尾关卡

• 只使用本轮已有证据判断：用户要求是否完成、是否混入无关修改、已有验证是否覆盖实际影响、是否改变持久项目事实。
• 证据充分时直接结束；不得仅因进入收尾阶段而重新读文档、重复测试或加载额外 Skill。发现具体缺口时，只执行能够关闭该缺口的最小操作。
• 最终状态必须明确为：完整完成、部分完成、受阻、仅完成诊断或无需修改。
• 本轮修改代码、测试、脚本、构建配置、数据结构或协议后，最终答复必须附一份供用户人工提交的 Commit 文稿；纯文档变更可按用户需要提供。
• Commit 文稿包含一个建议标题和必要正文。标题优先使用 type(scope): 中文摘要；存在不兼容变更时标记 ! 或 BREAKING CHANGE:。除非用户明确授权，不执行 git commit 或 git push。

Agent 任务日志

• 每个用户触发且最终形成答复的任务都必须记录；任务中途的补充要求合并到同一条记录。
• 收尾时只读取一次结束时间，并追加到 docs/worklogs/YYYY-MM-DD.md；每天一个文件，记录开始时间、结束时间、等级和明确状态。日志单独造成的文件变化不改变任务等级。
• 同一天自上而下必须是旧任务到新任务；通常把新任务追加到文件末尾，禁止把最新记录插到文件顶部。延迟补录的较早任务应将完整记录放到真实时间位置。
• L0/L1 只写一行独立二级标题：## HH:mm:ss–HH:mm:ss · Lx · 结果；文件：路径或无。，不加载日志 Skill，也不得作为列表项挂在前一任务下。
• L2-L5 加载 record-task-log，按等级记录已有结论；不得为写日志重新读实现、重复验证或复制原始输出。
• 日志只作为执行索引，不是项目事实来源。除非用户明确审查历史任务，否则开发时不读取旧日志。
• 日志写入本身不触发测试、构建、知识同步、TRACE 或 Commit 文稿。多仓库任务在每个实际修改的仓库记录，主要仓库写完整条目，其他仓库可简化。

TRACE 修改跟踪

• TRACE 不只记录最终改了什么，还必须追加跟踪“修改前基线 → 重要调整 → 最终状态”及其原因。
• L0/L1 不创建 TRACE；普通 L2/L3 也不为形式创建。复杂 L2、方案会演进的 L3 按需加载 track-change-trace；L4/L5 必须加载并在实质修改前建立任务编号。
• 每天使用一个 docs/traces/YYYY-MM-DD.md，同一天不同任务用稳定编号 T-HHmmss 区分。只在实质范围、方案、契约、数据、风险或验证方向改变时追加检查点，不记录工具流水。
• TRACE 自上而下按真实时间从旧到新排列；新任务块追加在文件底部。较早任务在已有后续任务后重新继续时，在文件底部追加同编号“继续”块，不回到上方插入最新检查点。
• TRACE 采用追加式更正，不改写旧检查点；最终检查点提供按组件或文件的“修改前 → 修改后”映射，并与同编号 worklog 互相链接。

完成条件

完成时应已实现用户要求或给出明确诊断、审查本任务差异、完成按比例验证、核对受影响的持久知识并说明剩余风险。不得创建没有未来价值的流程产物。

项目专属规则

• DESIGN.md 负责预期行为，ARCHITECTURE.md 负责包结构与不变量，README.md 负责安装和使用。
• 可移植核心不得依赖特定厂商的工具、模式或配置。
• 运行脚本默认只使用 Python 标准库，确有必要时才能引入依赖并说明理由。
• 修改 Skill 后运行标准 Skill 校验器；修改脚本后进行语法编译，并在临时仓库验证安装预演和审计。
• 开发本包时不得修改已接入项目，除非该项目明确属于本次接入或升级范围。
• 除路径、命令、代码标识符、标准名称和无法合理翻译的专有名词外，面向人的内容统一使用中文。