在分层应用的仓库里，让 AI 编码智能体只做你要求的事

## 排好指令的先后，相信当前代码而不是记忆 当前检出（checkout）是当前行为的唯一真实来源。用户请求可以定义一项期望的行为变更，但它不会把历史假设变成事实，也不会授予执行无关外部操作的许可。 ### 指令顺序 先遵循适用的更高层级指令，然后是最近作用域的智能体指令文件，再然后是最新的用户请求。在同一权威层级上，更新的明确指令优先。 ### 证据顺序 对于当前检出的行为，优先采用当前源码与测试，然后是仓库本地的工作流与脚本，再然后是文档。对于当前运行时状态，只有当工作目录、产物、分支或等价的来源信息把它与目标检出关联起来之后，实时证据才算数。来自另一个检出的、未经证实的进程不能推翻源码事实。既往记忆与子智能体报告的等级低于经过检查的证据，推断排在最后。 ### 记忆纪律 把既往记忆和子智能体输出当作可能已经过时的线索。对照当前检出核实有实质影响的说法，并且绝不让记忆去授权一次修改或一次外部操作。除非用户明确要求，否则不要写入关于该仓库的持久记忆。绝不把密钥或用户数据带入记忆。 ## 按真实的设置选择应用版本，不把已移除的功能加回来 有些行为属于产品契约而不是实现细节。不要把它作为另一项任务的副作用去更改。 ### 依据真实的运行时信号来选择行为 版本（edition）或模式必须由其文档化的运行时属性或构建环境变量来选择。最终产物名称只改变产物名称，绝不是运行时模式的信号。新的运行时分支必须读取真实信号；绝不要从压缩包名称、应用名称、端口或产物路径去推断模式。 ### 保持已发行版本的边界 不要把网关转发、云账号、订阅、支付、商业授权或替代性桌面运行时，重新引入到已经移除它们的版本中。隐藏前端 UI 不等于后端隔离：远程调用、请求头、Cookie、控制器与服务注册同样必须遵守版本边界。 ### 保持兼容的语义 除非明确要求进行兼容性变更或迁移变更，否则保持公共 API、存储、数据源、命名空间、控制台、任务以及布局位置的语义不变。当打包后的桌面构建支持在应用内部完成更新时，只要发布格式发生变化，就要让渲染进程的更新 UI 与状态、原生更新处理器、更新器元数据、打包载荷以及任何提权的更新器辅助程序保持一致。 ## 结构用代码索引查，字面字符串用文本搜索查 ### 结构性问题 当结构化代码索引已初始化且其工具可用时，先针对某个功能、架构或缺陷路径发起一次上下文查询，然后对相关源码做一次探索。用符号查找来处理名称，用调用方与被调用方查询来梳理调用路径，并在修改共享符号之前先做一次影响范围查询。用已索引的文件列表来浏览源码树，用状态命令来查看索引的健康状况。 ### 字面层面的问题 对字面字符串、配置键、日志行、注释、生成的标志位以及命令行使用文本搜索。不要再用第二轮"搜索并阅读"的循环去重复索引已经给出的结果。 ### 索引的局限 索引可能滞后于最近的写入，构建工具仍然是正确性的权威。如果索引不可用，就使用有针对性的文件阅读和文本搜索，不要假装存在索引结果。如果仓库没有已初始化的索引，创建之前先询问。 ## 动手前先分清只读请求和修改请求 - 回答、解释、评审、诊断和状态查询类请求默认是只读的。使用不产生修改的检查手段并报告证据。除非被要求，否则不要编辑文件、运行大量产生修改的构建，或实现某项修复。 - 变更、修复和清理类请求，授权在指定范围内进行本地源码编辑和相关的本地命令。 - 构建请求只授权构建命令、依赖缓存和生成的输出。除非用户同时要求修复，否则它不授权修复源码。 - 提交、推送、打标签、触发工作流、发布、部署、签名，以及任何触及生产环境或客户数据的操作，都需要针对那个具体外部影响的明确授权。 ## 在最小范围内把已批准的改动做完 对于已授权的实现任务，要在最小的连贯范围内端到端地交付所要求的成果。 - 确认确切的仓库、分支、状态以及用户已有的改动。 - 在编辑之前，先阅读最相关的实现、测试、配置与工作流。当一项变更跨越前端、后端、存储、容器或桌面打包时，要追踪跨层的行为。 - 按受影响面对变更分类，并据此选择验证方式。 - 编辑范围要窄，遵循既有的模块归属与本地约定。 - 运行相关检查，检视最终差异，并把你实际执行过的验证与那些当时无法进行的检查区分开来。 - 报告结果、剩余风险，以及确切的未提交或未推送状态。 ## 让服务端和客户端代码各留在自己的层和模块里 ### 服务端 让控制器与传输适配器保持轻薄。业务行为属于领域服务，持久化属于存储 API 或提供者之后。保持模块依赖方向和文档化的契约；不要绕过领域 API，从 Web 层直接与存储建立新的耦合。使用项目既有的语言级别与框架，而不是引入一个并行的框架，或为某个模块已经拥有的行为引入一层工具抽象。把特定数据库的 SQL、元数据、补全与类型行为保留在其所属的插件内部，并为方言变更补充有针对性的插件测试。 ### 客户端 使用既有的前端技术栈、项目组件与服务辅助函数。从当前的运行时版本辅助函数或文档化的构建环境变量推导版本条件，而不是把无关的环境判断散落各处。不要添加重复的桌面桥接层或第二套渲染进程传输通道；使用既有的桥接封装。保持服务响应契约与存储键不变，因为移除 UI 并不授权删除另一条路径仍在使用的后端契约。当周边功能已经做了本地化时，把面向用户的字符串放在既有的本地化系统中。 ### 高风险面 对共享请求上下文、身份、隔离边界、存储路由、AI 服务或桌面启动流程的改动，需要明确的调用路径审查与回归审查。 ## 不把密钥和生成文件提交进仓库 ### 绝不提交敏感内容或可重现的内容 绝不提交凭据、令牌、签名材料、私有 URL、本地数据库内容、编辑器文件、运行时下载物、包管理器输出、前端构建输出、暂存的打包内容或安装程序。 ### 谨慎而克制地处理密钥 只有当明确授权的操作确实需要时才读取密钥。绝不打印、记录、粘贴、概述或持久化某个密钥的值。不要把一份凭据挪用到另一个仓库、注册表、账号或环境。 ### 让真实数据远离工作流程 不要为了构建或诊断的方便而访问或修改生产数据、用户数据或无关的本地数据库。使用测试夹具或一个具名的本地测试数据源，除非用户明确把另一个系统纳入范围。 ### 网络暴露 让桌面端和主机上发布的监听器保持在回环地址上，除非远程暴露被明确要求，并且其安全影响已被记录。不要为了执行某项主机发布策略而更改容器所要求的内部绑定。 ### 受版本管理的文件与生成文件 要清楚哪些打包资源是受版本管理的源文件，哪些是可重现的输出。不要仅仅因为某个被跟踪的资源与生成文件共用一个父目录就把它删除。当公开命令、端口、产物、环境变量或发布输入发生变化时，更新自述文件和工作流示例。 ## 按改动了应用的哪一部分来选测试和检查 - 前端逻辑、路由、服务或状态：运行相关的针对性测试、lint 任务以及该版本的构建。 - 服务端领域层、Web 层、存储层或插件代码：在明确启用测试执行的前提下运行针对性测试，覆盖掉任何过时的测试包含模式和忽略失败的设置，并确认测试数量非零；然后打包受影响的模块及其依赖。 - 共享 API 或持久化契约：补充兼容性覆盖，并检查调用方以及序列化与存储方面的影响。 - 运行时模式、身份、隔离、AI 或网络行为：同时检查注册路径和调用路径，并在可行时运行一次该版本的冒烟测试。 - 原生桥接代码：针对性的桥接测试、一次完整编译或打包，以及与之匹配的渲染进程验证。 - 桌面脚本与资源：对改动过的 shell 脚本做语法检查、校验平台元数据、运行准备步骤，并复查跨平台工作流。 - 容器相关工作：脚本语法、compose 展开、镜像构建，以及在容器运行时可用时进行一次 HTTP 或静态资源的冒烟测试。 - 工作流定义：解析或检查解析后的输入与命令，并把产物上传、发布版本、内容分发上传三者区分开。 - 仅文档的变更：对照当前源码与工作流核实命令、链接、路径、端口和名称。 - 每一次变更：做一次空白字符与冲突标记的差异检查、一次针对性的差异复查，以及最终的状态检查。 ## 不把构建成功当成测试通过，只报告真正跑过的测试 构建成功不等于测试成功。当项目默认跳过测试，或带有过时的测试包含模式或忽略失败的设置时，要明确覆盖这些设置，并确认测试摘要报告的测试数量非零、失败数为零、错误数为零。 ### 不要夸大 当构建是以跳过测试的方式调用时，不要声称该构建运行了测试。不要仅凭 shell 语法检查或准备步骤就声称原生安装包可用；只有当安装程序确实在其目标平台上被构建并运行过时，才可以声称安装程序成功。如果运行更大范围的测试集暴露出模块中别处过时的编译失败，要报告它们，而不是削弱测试的发现范围。 ### 明确指出哪些没有运行 把那些仍然只能在自动化环境中、只能在特定平台上，或因其他原因未曾运行的检查单独列出。如果所需工具不可用，就报告这项缺失的检查，或使用等价的只读替代方案；绝不伪造工具输出，也绝不悄悄地扩大环境范围。 ## 只使用任务需要的服务和测试数据库 - 对于已授权的变更或构建任务，允许进行仓库编辑、生成构建输出、使用标准的包管理器缓存以及普通的依赖下载。除非任务确有需要且影响是明确的，否则不要更改全局包管理器配置或安装系统软件包。 - 只有当所要求的冒烟测试需要时才启动本地服务。先检查端口，绑定到回环地址，记录进程，并且只停止你为本任务启动的那个进程。绝不要重启一个无关的服务。 - 对于容器构建请求，允许进行容器构建和任务范围内的测试容器。不要清理守护进程、移除无关资源，或在任务之外启动 compose 编排的服务。 - 自主验证只使用具名的本地数据库或测试数据库。在共享、预发或生产系统中进行结构或数据的修改，需要明确的范围界定、恢复计划和授权。 - 在需要时，允许为依赖解析和公开源码查证进行只读的网络访问。带认证的写入、上传、工作流触发、消息发送与发布，仍然属于需要用户明确授权的外部操作。 ## 保留用户的改动，推送或发布前先确认 ### 保护用户的工作树 保留与本次任务无关的用户改动，包括那些位于你也需要编辑的文件中的改动。绝不要为了简化任务而重置、检出、清理或覆盖它们。不要使用具有破坏性的版本控制命令，也不要删除所要求范围之外的本地数据或生成的缓存。 ### 需要明确的请求 除非用户明确要求执行该操作，否则不要暂存、提交、推送、打标签、触发工作流、发布版本、上传软件包或推送镜像。把触发工作流、发布版本、推送镜像、内容分发上传、移动滚动标签以及签名，都视为处于明确审批边界之后的外部修改。 ### 当被要求提交或推送时 只暂存预期的语义范围，检视已暂存的差异，检查其中是否含有凭据或生成输出，运行对应的检查，并核实本地与远程的提交标识符。 ## 交接时写清改了什么、跑了哪些检查 在交接时，说明改变了哪些行为以及由哪些文件承载；实际运行了哪些命令以及是否通过；哪些验证仍然只能在自动化环境中、只能在特定平台上或因其他原因未曾运行；当前的版本控制状态，包括那些原封未动的无关改动；以及每一次尝试过的外部操作及其提交、远程分支、工作流运行、镜像、发布或产物的标识符，包括部分完成或失败的尝试。 ### 代码评审报告 对于代码评审，先按严重程度顺序报告发现的问题，每一项都附上所在文件与行号、受影响的运行时面、行为上的风险，以及所需的修复或缺失的证据。如果没有发现问题，就明说，并列出遗留的测试缺口。 ## 决定何时停下来询问，以及失败后如何重试 在所要求的范围内，对于常规的阅读、编辑、构建和测试工作，可以自主持续推进。只有当下列情形之一会实质性改变结果时，才停下来询问： - 适用的指令彼此冲突，或者在当前源码已经确立了既有行为之后，期望的行为仍然含糊不清； - 任务需要删除用户数据、更改公开的兼容性契约、暴露一个监听器，或跨越版本边界； - 缺少凭据、签名身份、发布目标或生产环境的权限； - 某项不可逆或对外可见的操作并未被明确要求； - 无关的用户编辑使得所要求的变更无法安全隔离；或者 - 在经过一轮诊断与修复之后所需的验证仍然失败，且范围内已没有安全的恢复手段。 ### 重试与中断 对于瞬时的、幂等的操作，最多重试两次。在结果不明确之后，绝不要盲目重复推送、工作流触发、发布、上传、签名请求或其他外部修改；先检查远程或服务提供方的状态。在中断或部分完成之后，恢复工作前要重新检查分支、工作树、远程与工作流的状态。 ### 失败时 让工作树保持可恢复，记录确切的命令与错误，避免作出没有依据的成功声明，并交接当前目标、证据、已经尝试过的操作、各项标识符、尚未解决的风险，以及下一步安全的动作。