code-engineering

# 编程代理模式 ## R — 原文 (Reading) > Claude Code 实现文件记忆、Agent 子任务委派、并行工具调用、Git 安全协议和"量两次切一次"原则；Codex 具备脏工作树感知、Plan 工具带跳过规则、代码审查按严重度排序；Jules 定义 plan→review→execute 生命周期，用 Playwright 验证前端；Claude Design 固定 React+Babel 版本并制定反 AI 糟粕指南。核心模式：安全优先 Git 工作流、计划生命周期管理、上下文感知编辑、验证循环、自主与引导模式。 ## I — 方法论骨架 (Interpretation) 1. **安全优先 Git 工作流**：任何破坏性操作（force push、hard reset、clean）需显式用户确认，优先创建新提交而非修改已有提交，保护主分支。 2. **计划生命周期管理**：采用 plan→review→execute 三阶段模型——先理解意图生成计划，用户确认后再执行，执行后验证结果。 3. **上下文感知文件编辑**：编辑前先读取文件内容，理解上下文后再修改，避免破坏性覆盖；优先使用差异编辑而非全文重写。 4. **验证循环**：代码修改后运行测试或构建验证，前端变更使用浏览器工具截图确认视觉效果。 5. **自主与引导模式切换**：简单任务可自主完成（YOLO 模式），复杂任务需逐步确认，根据任务性质自动选择模式。 6. **反 AI 糟粕规则**：禁止生成典型的 AI 风格代码（过度注释、不必要的抽象、冗余类型声明），追求简洁专业的工程代码。 ## A1 — 案例分析 (Past Application) ### 案例: Claude Code 的 Git 安全协议 - **问题**: 编程代理可能执行破坏性 Git 操作（如 force push 到主分支、hard reset 丢失未提交工作），导致代码资产损失。 - **设计模式的使用**: Claude Code 在系统提示中建立完整的安全协议——永不执行 destructive 操作除非用户明确要求、优先创建新提交而非 amend（amend 会覆盖前一次提交的历史）、提交前检查 hooks 是否通过、不跳过 --no-verify。同时要求在暂存文件时指定具体文件名而非 `git add -A`，避免意外包含敏感文件。 - **结论**: Git 安全不能依赖模型判断，必须在系统提示中以硬性规则形式声明，将高风险操作从"建议谨慎"升级为"必须确认"。 ### 案例: Jules 的 plan→review→execute 生命周期 - **问题**: 编程代理直接动手修改代码容易偏离用户意图，尤其是多文件变更时，错误修改的修复成本远高于规划阶段的修正成本。 - **设计模式的使用**: Jules 将编程任务分为三个阶段——Plan（理解需求、分析代码库、生成变更计划）、Review（展示计划供用户审核确认）、Execute（按计划执行修改）。前端变更还增加 Playwright 截图验证环节。 - **结论**: "量两次切一次"原则在编程代理中显著降低返工率，计划阶段的低成本修正远优于执行后的高成本修复。 ## A2 — 触发场景 (Future Trigger) ★ ### 用户在什么情境下需要? 1. 构建 IDE 内的 AI 编程助手（如 VS Code 插件） 2. 设计自主编程代理（如根据 Issue 自动修复代码的 CI/CD 机器人） 3. 开发命令行编程工具（如终端中的 AI 编程助手） 4. 实现代码审查自动化系统 ### 语言信号 - "AI 编程助手" - "自动修改代码" - "Git 操作自动化" - "代码审查 Agent" - "需要安全地编辑文件" ### 与相邻 skill 的区分 - 与 **injection-defense** 区别：注入防御关注外部内容的信任边界，编程代理关注代码执行操作的安全性（如 Git 破坏性操作防护） - 与 **citation-system** 区别：代码引用指向文件和行号而非文档段落，编程代理的引用是操作上下文的一部分 ## E — 可执行步骤 (Execution) 1. **步骤 1：建立 Git 安全协议** - 完成标准：列出禁止自主执行的 Git 操作清单（force push、hard reset、主分支直接推送、amend 已推送的提交），为每项定义用户确认流程和替代安全方案。 2. **步骤 2：设计 plan→review→execute 生命周期** - 完成标准：定义三阶段的输入输出——Plan 阶段输出变更文件列表和修改概要，Review 阶段要求用户确认，Execute 阶段按确认结果执行；规定何时可跳过 Review（如单行修改等低风险变更）。 3. **步骤 3：定义上下文感知编辑规则** - 完成标准：声明"编辑前必须先读取文件"原则，优先使用差异编辑（指定 old_string/new_string）而非全文重写，暂存文件时指定具体路径而非 glob 通配。 4. **步骤 4：添加验证循环机制** - 完成标准：规定代码修改后的验证步骤——运行相关测试套件、执行构建检查、前端变更使用截图工具确认视觉效果；定义验证失败时的回退策略（撤销修改并报告错误）。 5. **步骤 5：编写反 AI 糟粕指南** - 完成标准：列出禁止的 AI 典型代码风格（过度注释如"// 这是一个变量"、不必要的接口抽象、冗余的类型重定义、千篇一律的错误处理模式），提供良好与糟糕示例的对比。 ## B — 边界 (Boundary) ★ ### 不要在以下情况使用 - 纯代码问答或教学（无文件修改操作，无需 Git 安全协议） - DevOps 基础设施配置（Terraform、Kubernetes manifest 等，属于运维领域） - 代码分析工具（仅读取不修改，无需编辑安全协议） - CI/CD 流水线设计（属于自动化部署，非代码编辑） ### 常见失败模式 - **过度自主**：编程代理未经确认直接执行复杂修改，导致偏离用户意图或破坏现有功能，应强制对高风险操作设置确认环节 - **全文重写偏好**：模型倾向于重写整个文件而非局部修改，增加引入意外错误的风险，应优先使用差异编辑 - **忽视工作树状态**：在脏工作树中执行操作导致未保存变更丢失，应要求操作前检查工作树状态 - **AI 糟粕代码**：生成过度注释、不必要抽象、冗余类型的"AI 风格"代码，需明确的反模式指南约束