通俗解读：Agent Harness (PiG / KiloCode)

本文阐述了我所使用的编码智能体工作流中的五个主要组件。其目的很简单：理解智能体如何接收指令、保存上下文、学习工作流程并遵循软件开发原则。

我们无需从技术术语开始。我们将使用员工、操作手册和日志本的类比，以便更容易理解这些概念。

注意：本文结合了通用编码智能体概念与我个人的配置。并非所有智能体都拥有相同的机制或文件结构。具体技术细节需参考各自智能体的文档。

1. 技能（Skills）——工作手册

什么是技能？

想象一下，AI 智能体就像是一个非常聪明但还不了解我们工作方式的新员工。

他知道如何编写代码、理解指令和解决问题。但他可能还不知道：

• 我们喜欢以何种方式编写提交信息（commit message）。
• 我们使用的月度报告格式。
• 部署到服务器的步骤。
• 项目中的安全标准。
• 我们管理 Laravel 项目的方式。

技能是教导智能体按照我们的需求执行特定任务的指南。

区分能力（Capability）与知识（Knowledge）

扩展或工具赋予智能体使用 Git 的“双手”，而技能则教它如何写出我们所需的提交信息。

技能是如何工作的？

在 PiG 中，技能的一种形式是存储在 skill 目录下的 SKILL.md 文件。

~/.pig/skills/commit/SKILL.md

文件内容可以说明技能名称、用途以及需要遵循的指令。

---
name: commit
description: 按照项目格式编写提交信息。
---

请使用以下格式：

type(scope): summary

摘要必须简洁明了。
如有必要，请在正文中解释变更原因。
不要包含不相关的变更。

当智能体发现该技能时，它可以在需要时使用所提供的信息和指令。

技能的加载和使用方式取决于智能体的实现。不要假设所有智能体都会在会话开始时读取每个技能的全部内容。

PiG 如何发现技能？

PiG 支持显式加载技能，包括使用 --skill 选项，以及从受支持的目录进行自动发现机制。

pig --skill commit

所使用的目录必须符合相应版本 PiG 所支持的结构和配置。

为什么技能很有用？

没有技能，我们可能需要反复解释相同的工作流程。

有了技能，我们可以保存这些指南并重复使用它们。

这就像是为人类员工制定的标准作业程序（SOP）。

总结：技能是可重复使用的特定工作指南，使智能体能够遵循我们所要求的工作方法。

1. AGENTS.md —— 固定规则手册

如果技能是针对特定任务的指南，那么 AGENTS.md 可用于为在某个项目中工作的智能体设定一般规则和指令。

例如，在开始工作之前，我们希望智能体理解以下规则：

• 未经批准不得修改敏感文件。
• 在进行更改前检查项目结构。
• 对 Laravel 输入验证使用 Form Request。
• 未经批准不得进行部署。
• 在宣布工作完成前验证变更结果。

此类指令适合放置在项目指令文件中。

AGENTS.md 应该包含什么？

在我的工作流中，内容包含以下几个方面。

这是我用来管理自己工作流的排列方式，并非所有编码 Agent 都必须遵循的格式。

为什么文件名很重要？

Agent 并不一定会读取项目目录中的所有 Markdown 文件。

它通常有特定的机制来查找已知的指令文件。PiG 有自己的上下文加载规则，而 KiloCode 也有自己的指令和配置机制。

因此，不要假设名为 Agent.md、AGENTS.md 或 CLAUDE.md 的文件会被所有 Agent 以相同的方式处理。

如果我们希望使用特定的指令文件，请查阅所用 Agent 的文档，并确保该文件确实被加载。

为什么 AGENTS.md 需要简洁？

始终被纳入 Agent 上下文的指令会占用一部分可用的 token。

因此，我更喜欢将重要的通用规则放在主指令文件中。特定任务的详细指南可以保存在 skills 或单独的参考文档中。

总结：AGENTS.md 是放置 Agent 指令和工作边界的地方。确保其内容清晰、相关，并且确实被所使用的 Agent 读取。

1. brain/ — 工作记忆库

试图解决的问题

当对话会话结束时，Agent 在下一次会话中可能不再拥有所需的全部工作上下文。

想象我们正在开发一个 Laravel 系统。我们已经检查了数据库，修改了一些文件，并发现了一个问题。第二天，我们开启一个新的会话。

如果上下文没有保存，我们可能不得不重复相同的检查步骤。

这就是 brain/ 概念发挥作用的地方。

在我的工作流中，brain/ 是一个用于存储工作笔记的目录，以便 Agent 在后续会话中可以重新读取这些笔记。

这并不意味着 AI 模型突然拥有了永久记忆。信息之所以保留，是因为我们将它们存储在文件中，并指示 Agent 再次引用它们。

工程师日志簿的类比

工程师的日志簿通常记录以下内容：

• 已完成的工作。
• 发现的问题。
• 做出的决策。
• 尚未完成的事项。
• 下一步行动。

brain/ 采用了相同的概念。

brain/ 的结构示例

以下是我用作工作约定的结构示例：

brain/
├── task.md
├── walkthrough.md
├── architecture.md
├── ai_guidelines.md
├── gaya-penulisan.md
└── decisions/
    ├── 001-database.md
    └── 002-authentication.md

此结构并非 PiG 或 KiloCode 的强制结构。它是一种可根据项目进行调整的文档设计。

Mental Anchor（思维锚点）—— 继续工作的标记

我使用的一个概念是 Mental Anchor。

在每次会话记录的末尾，Agent 需要指明实际位置，以便继续工作。

当前状态

• 迁移已检查。
• Form Request 已更新。
• 功能测试在授权用例中仍然失败。

思维锚点： 在修改生产代码之前，先调查功能测试中授权失败的原因。

思维锚点帮助代理知道下一轮会话的合适起点。

然而，这些记录仍需与仓库的实际状态进行核实。文件可能在记录编写后发生变化。

我工作流中的两种“大脑”类型

我将全局记录与特定项目记录区分开来。

这些位置是我个人的约定，并非 PiG 或 KiloCode 自动保证读取的标准位置。

需要指示代理读取正确的位置。如果存在全局和项目记录，还需要设定优先级规则，以避免上下文冲突。

重要规则

1. 不要在 brain 文件中保存密码、API 令牌或其他秘密信息。
2. 记录实际发生的情况，而不是假设的情况。
3. 明确说明尚未解决的问题。
4. 记录重要决策及其原因。
5. 在适当情况下，使用 Git 跟踪文档文件的变更。

总结：brain/ 是一个工作记录系统，有助于在会话之间保持上下文，前提是代理能够正确读取和更新这些记录。

1. ai_guidelines.md — 工作哲学与思维方式

如果说 AGENTS.md 阐述了工作指令和边界，那么 ai_guidelines.md 则阐述了指导我工作方式的核心原则。

它不是魔法配置文件。这是一份包含我希望在 AI 辅助软件开发过程中坚持的原则的文档。

简单类比

• AGENTS.md：不要闯红灯。
• ai_guidelines.md：我相信安全比快速到达更重要。

前者设定了指令。后者解释了我们要工作方式背后的原则。

核心原则

在我的工作流中，以下原则至关重要：

1. 人类理解并承担责任

AI 协助提供解决方案，但我必须理解、验证并对最终决定负责。

1. 简洁的代码胜过炫技的代码

易于阅读和维护的解决方案通常优于看似精彩但难以理解的代码。

1. 安全始于设计

安全不是系统完成后附加的工作。它需要在开发初期就予以考虑。

1. 变更前先核查

代理在进行更改之前需要了解项目的真实状况。不要在没有检查的情况下假设结构、依赖项或配置。

1. Git 和部署始终由人类控制

代理可以提供更改、运行测试并报告结果。在我的工作流中，提交（commit）、推送（push）和部署（deploy）的决定权始终掌握在人类手中。

1. 不确定时要坦诚

如果某项指令失败，代理应报告失败情况，而不是声称工作已完成。

我的核心原则

AI 协助。Hardy 理解、验证并拥有最终决定权。

AI assists. Hardy understands, verifies, and owns the final decision.

当代理需要理解我所偏好的开发方法时，可参考此文档。为确保其真正被使用，主要指令需告知代理何时以及如何读取该文件。

总结：ai_guidelines.md 是我希望在 AI 辅助软件开发中坚持的原则和工作方法的参考。

1. soul.md — Agent 的深层目标与哲学

如果 ai_guidelines.md 提供了工作原则的概要，那么 soul.md 则用于在我的工作流中更深入地阐述这些原则。

soul.md 这个名字并不意味着代理拥有像人类一样的灵魂或意识。它是我选择用来存储代理的设计哲学和目标的文件名。

三个文件之间的区别

• AGENTS.md 是规则手册。
• ai_guidelines.md 是桌面上的简要笔记。
• soul.md 是解释原则背后原因的文件。

soul.md 包含什么内容？

在我的设计中，该文档涵盖了以下原则：

• 安全优先：从一开始就考虑安全性。
• 人类判断优先：人类对决策保持最终责任。
• 验证而非假设：验证比假设更重要。
• 生产就绪：进行修改时考虑到可维护性和恢复能力。
• 自托管实用主义：在适当的情况下优先考虑开源和自托管解决方案。
• 学习基础：理解 Linux、网络、SQL 和软件开发的基础知识。
• CLI 透明性：显示实际的命令和结果，以便工作可被理解。
• 备份与回滚：在实施有风险的变化之前规划恢复方案。
• 文档记录：文档工作是工作的一部分。
• 保留上下文：保存重要信息以供下一次会话使用。
• 有界步骤：以受控和分阶段的方式做出更改。
• 代理边界：不伪造结果、不隐藏错误或不声称在没有证据的情况下的成功。

这些原则构成了我希望建立的工作流身份，而不是模型中自动保证具备的能力。

心理锚点 — 主要工作循环

在我的工作流中，代理的工作遵循以下循环：

理解
    ↓
检查
    ↓
计划
    ↓
变更
    ↓
验证
    ↓
文档记录
    ↓
下一个任务

1. 理解：弄清需求和存在的问题。
2. 检查：查看系统的实际状态。
3. 计划：确定所需的更改。
4. 变更：以受控方式实施更改。
5. 验证：运行适当的测试或检查。
6. 文档记录：记录更改和验证结果。
7. 下一个任务：确定下一步骤。

这个循环有助于防止代理在未理解问题的情况下直接修改代码。

我坚持的一个原则

完成工作，验证工作，并为下一个人——或下一次会话——留下足够的证据，以便他们能够理解所做的工作。

完成工作，验证其结果，并留下充分的证据，使他人或后续会话能够理解所完成的工作。

总结：soul.md 是一份深入阐述目标、原则和方法的哲学文档，我希望将其作为编码代理工作流的指导方针。

1. 全局视角 — 工作流的五个层次

在理解每个组件之后，我们可以看看它们如何相互补充。

soul.md
   ↓
工作的哲学和目标

ai_guidelines.md
   ↓
开发的原则和方法

AGENTS.md
   ↓
指令和工作边界

brain/
   ↓
跨会话的上下文和笔记

skills/
   ↓
特定任务的指南

每个组件都回答不同的问题。

尽管这五个组件各不相同，但它们都有助于构建更一致的工作流。

然而，其有效性取决于代理的配置方式、实际读取的文件以及存储信息的准确性。

1. 结论

对我而言，使用编码代理不仅仅是发出提示并等待代码完成。

我希望代理能够理解其工作边界，遵循项目指南，保持上下文连贯，并验证变更结果。同时，我希望工作流程保持透明，以便我能从每一次变更中学习。

这五个组件有助于分担这些责任：

• Skills（技能）：特定任务的指南。
• AGENTS.md：指令和工作边界。
• brain/：工作笔记和上下文。
• ai_guidelines.md：开发原则。
• soul.md：支撑工作流的底层哲学。

并非所有项目都需要这五个组件。小型项目可能只需简单的指令和一些技能即可满足需求。更复杂的项目可能需要更结构化的决策记录、架构文档和会话笔记。

重要的是，不要仅仅因为看起来酷炫而构建过多的层级。只使用真正对工作有帮助的东西。

对我而言，最终的原则很简单：

Handle the routine. — 处理例行工作。

Surface the overlooked. — 揭示可能被忽视的事项。

Explain the complicated. — 解释复杂内容。

Verify the important. — 验证重要事项。

Preserve what was learned. — 保留所学内容。

Leave the human in control. — 让人类掌控最终决策。

这就是我希望能建立的编码代理工作流基础：AI 协助执行任务，但人类依然理解系统、验证结果并对决策负责。

本文在 AI 的辅助下撰写。