Tools

Harness Engineering：OpenAI 智能体工程总结 [!abstract] 这篇文章真正讨论的重点，不是“AI 会不会写代码”，而是“怎样搭建一个让智能体持续稳定地产出代码、测试、文档与修复的工程系统”。 [!note] 这是一份基于原文的整理版总结，偏重方法论提炼，不是逐段直译。 标题怎么理解 Harness Engineering 如果直译并不自然。结合全文语境，我更倾向把它理解为： 面向智能体的工程编排 为智能体设计工作环境、约束和反馈回路的工程实践 也就是说，重点已经不只是“让模型写代码”，而是让它在一个可读、可测、可验证、可修复的系统里持续工作。 一句话总结 OpenAI 用一个很小的工程团队，在几个月内做出了一个已经有真实用户使用的内部产品；在这个过程中，人类几乎不直接写代码，而是把主要精力放在搭建代码仓库结构、文档体系、工具链、架构约束、可观测性和自动反馈回路上，让 Codex 能稳定地产生、验证、修复并合并变更。 文章的核心信息 1. 人类从“写代码”转向“设计系统” 文章里最关键的一句话可以概括为：人类掌舵，智能体执行。 工程师的主要职责不再是亲手补实现，而是： 把目标拆成智能体能完成的任务 提供足够清晰的上下文和约束 设计反馈回路，让智能体自己发现问题并修复 当智能体做不好一件事时，重点不是“再提示一次”，而是追问：是不是缺工具、缺文档、缺规则、缺可观察性。 2. AGENTS.md 应该是地图，不该是百科全书 他们早期试过写一个超大的 AGENTS.md，结果失败了。原因很直接： 上下文窗口是稀缺资源 规则太多以后，模型会丢失重点 大而全的说明很快就会过期 单文件很难机械检查和持续维护 所以更好的做法是： 用简短的 AGENTS.md 充当导航地图 把真正的知识沉淀到结构化的 docs/ 中 给设计文档、执行计划、产品规格、架构说明和质量评分做索引 这本质上是在做渐进式披露：先给入口，再按需深入，而不是一次性把所有东西塞给模型。 3. 代码仓库要成为唯一可信的记录系统 对智能体来说，拿不到上下文就等于不存在。 所以那些只存在于聊天记录、口头讨论、Google Docs 或人脑里的决策，实际上都无法被智能体可靠地复用。文章强调，应该把越来越多的重要上下文沉淀回仓库，包括： 架构原则 产品约束 设计决策 执行计划 技术债状态 代码质量标准 这样智能体才能基于版本化的、可检索的材料持续工作。 4. 不只是代码要可读，应用本身也要对智能体可读 他们做了很多“让智能体自己看得见系统状态”的建设，比如： 支持基于 git worktree 启动独立应用实例 把浏览器调试能力接入智能体运行时 提供 DOM 快照、截图、导航等能力 把日志、指标、链路追踪也暴露给智能体查询 这样智能体就不只是“改代码”，还可以： ...

RIPER-5 背景介绍 你是Claude 4.0，集成在 Copilot 中，Copilot 是基于AI的VS Code插件。由于你的高级功能，你往往过于急切，经常在没有明确请求的情况下实施更改，通过假设你比用户更了解情况而破坏现有逻辑。这会导致对代码的不可接受的灾难性影响。在处理代码库时——无论是Web应用程序、数据管道、嵌入式系统还是任何其他软件项目——未经授权的修改可能会引入微妙的错误并破坏关键功能。为防止这种情况，你必须遵循这个严格的协议。 语言设置：除非用户另有指示，所有常规交互响应都应该使用中文。然而，模式声明（例如[MODE: RESEARCH]）和特定格式化输出（例如代码块、清单等）应保持英文，以确保格式一致性。 元指令：模式声明要求 你必须在每个响应的开头用方括号声明你当前的模式。没有例外。 格式：[MODE: MODE_NAME] 未能声明你的模式是对协议的严重违反。 初始默认模式：除非另有指示，你应该在每次新对话开始时处于RESEARCH模式。 核心思维原则 在所有模式中，这些基本思维原则指导你的操作： 系统思维：从整体架构到具体实现进行分析 辩证思维：评估多种解决方案及其利弊 创新思维：打破常规模式，寻求创造性解决方案 批判性思维：从多个角度验证和优化解决方案 在所有回应中平衡这些方面： 分析与直觉 细节检查与全局视角 理论理解与实际应用 深度思考与前进动力 复杂性与清晰度 增强型RIPER-5模式与代理执行协议 模式1：研究 [MODE: RESEARCH] 目的：信息收集和深入理解 核心思维应用： 系统地分解技术组件 清晰地映射已知/未知元素 考虑更广泛的架构影响 识别关键技术约束和要求 允许： 阅读文件 提出澄清问题 理解代码结构 分析系统架构 识别技术债务或约束 创建任务文件（参见下面的任务文件模板） 创建功能分支 禁止： 建议 实施 规划 任何行动或解决方案的暗示 研究协议步骤： 创建功能分支（如需要）： 1 git checkout -b task/[TASK_IDENTIFIER]_[TASK_DATE_AND_NUMBER] 创建任务文件（如需要）： 1 mkdir -p .tasks && touch ".tasks/${TASK_FILE_NAME}_[TASK_IDENTIFIER].md" 分析与任务相关的代码： ...

总体纲领 在coding之前 我们需要先有个draft(草案) 包含 背景 约束条件 设计的目的与折中 存在的问题以及改进这四个部分 背景 目标： 精准复现、定位并理解技术问题的本质、影响范围及业务上下文。 关键活动： 问题复现与场景描述 (Reproduce & Describe): 复现路径： 明确稳定复现问题的具体步骤、输入和环境（开发、测试、生产环境；特定用户/数据）。 异常表现： 清晰描述“不符合预期”的具体行为，包括错误日志、监控指标异常（延迟、错误率、资源使用率）、UI/API 表现等。 预期行为： 明确在同样场景下，系统 应该 表现出什么样的行为。 根因分析 (Root Cause Analysis - RCA): 信息收集： 收集相关日志、Metrics、Traces、Dump 文件、配置信息、代码版本、变更历史。 关联分析： 分析时间线，将问题现象与系统变更、流量波动、依赖服务异常等进行关联。 假设与验证： 提出可能的根因假设，并通过调试、日志分析、实验等手段进行验证或排除。 影响评估 (Impact Assessment): 业务影响： 评估问题对用户、业务流程、收入、SLA/SLO 的具体影响。 技术影响： 评估问题对系统其他模块、数据一致性、安全性的潜在影响。 现状审视 (Review Current State): 审视当前代码库、架构设计、技术文档中与问题相关部分。 了解是否存在已知的类似问题或临时的 Workaround。 产出： 一份详尽的 技术问题分析报告 (Technical Problem Report / RCA Report)，包含复现步骤、根本原因、影响范围和相关证据。 约束条件 目标： 明确解决方案必须遵守的技术边界和需要达成的技术/业务指标。 关键活动： 识别技术约束 (Identify Technical Constraints): 平台/语言/框架： 必须使用的编程语言、框架、操作系统、云平台等。 架构/兼容性： 必须兼容的现有系统架构、API 接口、数据格式、老版本等。 资源限制： CPU、内存、存储、网络带宽、预算等硬性限制。 规范/安全： 必须遵守的编码规范、安全标准、合规要求。 定义技术目标 (Define Technical Goals): 功能性目标： 解决方案需要实现的核心功能。 非功能性目标 (NFRs): 明确性能（延迟、QPS）、可用性 (Availability)、可靠性 (Reliability)、可伸缩性 (Scalability)、可维护性 (Maintainability)、可测试性 (Testability) 等方面的具体指标要求。 明确核心假设 (Identify Technical Assumptions): 方案设计所依赖的底层库行为、第三方服务承诺、网络环境稳定性等假设。 产出： 一份 技术规格与约束清单 (Technical Specifications & Constraints List)，作为设计方案的输入和评判标准。 ...

go 的代码风格 git commit 规范 git 教程 The Uber Go Style Guide

说明 文档中使用的关键字「MUST」,「MUST NOT」,「REQUIRED」,「SHALL」,「SHALL NOT」,「SHOULD」,「SHOULD NOT」,「RECOMMENDED」,「MAY」和「OPTIONAL」在 RFC2119 中有说明。 还未定稿，对规范中提及的点有不赞同的欢迎提出 issues（请添加 markdown 标签）讨论。 规则 后缀必须「MUST」使用 .md。 文件名必须「MUST」使用小写，多个单词之间使用-分隔。 文件编码必须「MUST」用 UTF-8。 文档标题应该「SHOULD」这样写。 1 2 Markdown 编写规范 ========================== 章节标题必须「MUST」以 ## 开始，而不是 #。 章节标题必须「MUST」在 # 后加一个空格，且后面没有 #。 1 2 3 4 5 6 7 8 // bad ##章节1 // bad ## 章节1 ## // good ## 章节1 章节标题和内容间必须「MUST」有一个空行。 1 2 3 4 5 6 7 8 9 10 11 // bad ## 章节1 内容 ## 章节2 // good ## 章节1 内容 ## 章节2 代码段的必须「MUST」使用 Fenced code blocks 风格，如下所示： ...