Buildr: Instructions file for Codex

AGENTS.md

Buildr 工作空间规则

Buildr 产品及其生成的工作空间（Workspace）共同遵守本规则。

智能体优先原则

本节指导智能体参与的工作协作；用于产品与架构设计时，适用于引入智能体交付产品结果的部分。软件引入智能体（Agent），参与理解用户目标、判断或执行工作并交付产品结果，就开始向智能体软件（Agentic Software）演进，不要求所有功能同时改造。仅使用智能体开发软件，不自动要求该产品采用智能体优先架构；尚未引入智能体的功能沿用适合自身目标的设计，既有业务规则、安全与授权边界保持有效。

智能体（Agent）是软件能力的主要执行者；人负责目标、约束、判断、授权和结果验收。

产品原则

1. 以目标驱动协作。人负责表达目标、约束、判断和授权；智能体在授权边界内理解目标并持续推进。不得把本可由智能体完成的过程重新拆成人工操作步骤。
2. 以真实工作现场为中心。对话用于表达和解释，界面用于认知和直接操作。真实工作现场由代码、文档、数据、环境和外部系统等工作对象的当前事实构成。智能体每次继续工作时，应重新核对当前事实，不能只依赖历史对话。
3. 以产物为核心组织协作。产物（Artifact）包括工作过程中形成或改变的中间成果与最终结果。产品应围绕这些成果组织交互、执行与验收，使其能够被独立查看、修改和接续，不依附于某次对话。不同入口的变化应可被其他参与者发现，人和智能体应依据当前成果继续工作；成果一致不等于目标完成，仍须按目标验收。

架构原则

1. 提供确定性能力，开放组合方式。软件能力应明确作用对象及其身份或版本、输入、输出、副作用、授权和失败边界。智能体根据现场动态组合这些能力；重复且稳定的组合再沉淀为确定性工作流（Workflow）。
2. 多种入口共享同一当前事实。人、智能体、界面和接口都可能改变工作现场。所有入口必须对齐同一对象身份和已观察版本；冲突必须显式处理，不得静默覆盖。各入口应能发现相关变化，继续判断或修改前核对当前事实，写入时校验已观察版本；人应能查看同一成果及必要变化，无需阅读完整执行过程。对话会话（Session）不能成为产品状态的唯一权威。不要求所有操作属于同一次执行（Run），也不要求每次变化立即唤醒智能体。
3. 约束局部化，失败影响隔离。每项能力只校验自身正确执行所必需的条件。局部缺陷只能阻止相关动作，不得扩大为整个目标或其他安全工作的阻塞；产品内部错误不得否定已经成立的事实，包括内部登记、派生证据或自动化信心不足，不得否定可从权威来源验证的事实。

性能原则

1. 以可信完成目标的效率衡量性能。首先保证目标正确、真实地完成，再减少完成目标所需的时间、步骤、词元（Token）、工具调用、重复尝试和人工介入。新增状态、门禁和流程必须证明其收益大于成本。验证范围应与改动影响匹配；已有检查仍适用于当前成果且必需检查已通过时，只有新改动、失败或明确未解决的风险才补充相关验证。

责任与治理

• Buildr 负责治理长期工作资产与少量确定性边界，不成为另一个智能体或通用许可层。
• 智能体（Agent）向用户说明目标、结果、影响与必要决定，不把 Buildr 内部术语和流程问题转交用户。
• 除非用户明确在开发 Buildr，发布版 Buildr 的用户不承担 Buildr 内部问题的诊断、修复或操作责任；只有涉及用户授权或业务判断时，才向用户请求决定。
• 用户明确指令优先于技能（Skill）的一般做法；业务约束、授权边界与实际权限继续有效。同一任务中已取得的授权，在对象、范围和副作用未改变且未被撤回时继续适用，不因换轮次重复确认。
• 用户明确要求“收尾”或等价的本轮交付，即授权当前任务范围内可核验的常规 Git 提交、集成和普通推送；不得仅因未逐项列出这些动作而重复询问。同意实施、开始或继续修改只授权实施范围内的持久修改与常规验证，不构成“收尾”、交付或等同指令。每次写入仍须核验真实仓库、内容归属、目标引用、完整推送范围和实际副作用；范围或目标不明时只停止受影响的写入。强推、merge commit、改写共享历史、丢弃内容、覆盖他人工作、删除远端分支、发布和语义冲突取舍不属于该授权。
• 任务级临时引用（如任务分支（Branch））的远端生命周期全程受明确授权约束：没有用户指令、任务声明的交付方式或适用于该仓库的持续授权时，不得把任务分支推送到远端；收尾必须处置本任务实际存在的远端任务引用——归属、交付保全与删除授权均证明时按实时观察提交删除，授权或安全条件不满足时逐项报告保留原因，不得静默残留。仓库声明的常驻引用与发布引用不适用本条，后者由发布能力按绑定政策处理。
• 只有继续推进会造成越权、错误对象写入、未经授权的外部或不可逆副作用、证据失真、完成误报或覆盖他人工作时，才关闭式失败。需要决定时，先完成不依赖该决定的已授权工作，再展示具体影响；若技能（Skill）要求暂停，链接对应 SKILL.md 并引用适用条款，区分明文要求与自身判断。