Code Engineering

编程代理模式

R — 原文 (Reading)

> Claude Code 实现文件记忆、Agent 子任务委派、并行工具调用、Git 安全协议和"量两次切一次"原则；Codex 具备脏工作树感知、Plan 工具带跳过规则、代码审查按严重度排序；Jules 定义 plan→review→execute 生命周期，用 Playwright 验证前端；Claude Design 固定 React+Babel 版本并制定反 AI 糟粕指南。核心模式：安全优先 Git 工作流、计划生命周期管理、上下文感知编辑、验证循环、自主与引导模式。

I — 方法论骨架 (Interpretation)

• 安全优先 Git 工作流：任何破坏性操作（force push、hard reset、clean）需显式用户确认，优先创建新提交而非修改已有提交，保护主分支。
• 计划生命周期管理：采用 plan→review→execute 三阶段模型——先理解意图生成计划，用户确认后再执行，执行后验证结果。
• 上下文感知文件编辑：编辑前先读取文件内容，理解上下文后再修改，避免破坏性覆盖；优先使用差异编辑而非全文重写。
• 验证循环：代码修改后运行测试或构建验证，前端变更使用浏览器工具截图确认视觉效果。
• 自主与引导模式切换：简单任务可自主完成（YOLO 模式），复杂任务需逐步确认，根据任务性质自动选择模式。
• 反 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) ★

用户在什么情境下需要?

• 构建 IDE 内的 AI 编程助手（如 VS Code 插件）
• 设计自主编程代理（如根据 Issue 自动修复代码的 CI/CD 机器人）
• 开发命令行编程工具（如终端中的 AI 编程助手）
• 实现代码审查自动化系统

语言信号

• "AI 编程助手"
• "自动修改代码"
• "Git 操作自动化"
• "代码审查 Agent"
• "需要安全地编辑文件"

与相邻 skill 的区分

• 与 injection-defense 区别：注入防御关注外部内容的信任边界，编程代理关注代码执行操作的安全性（如 Git 破坏性操作防护）
• 与 citation-system 区别：代码引用指向文件和行号而非文档段落，编程代理的引用是操作上下文的一部分

E — 可执行步骤 (Execution)

• 步骤 1：建立 Git 安全协议 - 完成标准：列出禁止自主执行的 Git 操作清单（force push、hard reset、主分支直接推送、amend 已推送的提交），为每项定义用户确认流程和替代安全方案。
• 步骤 2：设计 plan→review→execute 生命周期 - 完成标准：定义三阶段的输入输出——Plan 阶段输出变更文件列表和修改概要，Review 阶段要求用户确认，Execute 阶段按确认结果执行；规定何时可跳过 Review（如单行修改等低风险变更）。
• 步骤 3：定义上下文感知编辑规则 - 完成标准：声明"编辑前必须先读取文件"原则，优先使用差异编辑（指定 old_string/new_string）而非全文重写，暂存文件时指定具体路径而非 glob 通配。
• 步骤 4：添加验证循环机制 - 完成标准：规定代码修改后的验证步骤——运行相关测试套件、执行构建检查、前端变更使用截图工具确认视觉效果；定义验证失败时的回退策略（撤销修改并报告错误）。
• 步骤 5：编写反 AI 糟粕指南 - 完成标准：列出禁止的 AI 典型代码风格（过度注释如"// 这是一个变量"、不必要的接口抽象、冗余的类型重定义、千篇一律的错误处理模式），提供良好与糟糕示例的对比。

B — 边界 (Boundary) ★

不要在以下情况使用

• 纯代码问答或教学（无文件修改操作，无需 Git 安全协议）
• DevOps 基础设施配置（Terraform、Kubernetes manifest 等，属于运维领域）
• 代码分析工具（仅读取不修改，无需编辑安全协议）
• CI/CD 流水线设计（属于自动化部署，非代码编辑）

常见失败模式

• 过度自主：编程代理未经确认直接执行复杂修改，导致偏离用户意图或破坏现有功能，应强制对高风险操作设置确认环节
• 全文重写偏好：模型倾向于重写整个文件而非局部修改，增加引入意外错误的风险，应优先使用差异编辑
• 忽视工作树状态：在脏工作树中执行操作导致未保存变更丢失，应要求操作前检查工作树状态
• AI 糟粕代码：生成过度注释、不必要抽象、冗余类型的"AI 风格"代码，需明确的反模式指南约束