企业官网建设流程全解析

我用 Kiro CLI 用了大概一年，真正让效率发生质变的，不是开箱即用的通用助手，而是开始自己动手配置自定义 Agent。所谓自定义 Agent，简单说就是给终端里的这个 AI 助手重新定义“身份、能力边界和工作习惯”，让它针对你的项目、团队规范和个人工作流，给出稳定、可复用的输出。这篇内容我会从设计思路讲到完整配置，再配合实际案例和排查经验，尽量覆盖你在入坑过程中会遇到的绝大多数问题。适合已经在终端里用过 Kiro CLI、但觉得默认行为不够顺手的人，也适合完全没接触过自定义 Agent、想系统了解配置文件怎么落地的朋友。

1. 为什么要在 Kiro CLI 里自定义 Agent

1.1 一个通用助手远远不够

Kiro CLI 开箱后默认会有一个通用 Agent，能力很全，但你实际用起来会发现一个尴尬的问题：它太“万金油”了。今天让它帮忙看一段日志，明天让它写一个脚本，后天又让它生成 commit message。默认人格不可能在这么多任务里都表现到最好，因为它的指令本质上是一套平均化的提示词，没有针对任何具体场景做过优化。

我最早犯的错误是企图通过每次对话时重复"你现在是一个资深日志分析专家"来补救。这个做法能用，但非常痛苦：每次都要输入一大段话，偶尔漏了一个关键约束，输出质量马上掉一半。真正解决这个问题的方式，就是把这种"每次都重复的设定"固化成一个自定义 Agent。一次配置，之后调用只需要输入文件名，剩下的交给配置文件。

1.2 自定义 Agent 能解决什么具体问题

自定义 Agent 在团队协作场景里的价值尤其明显。我们团队曾经接了一个维护多年的老项目，代码风格非常独特，commit message 也有自己的格式规范。新人上手时默认助手完全不知道这些约定，提交记录经常被 reviewer 打回来。后来我把团队的代码规范、提交格式、禁止事项写进了一个独立 Agent，命名成"团队规范助手"，每个人都用同一个配置。从那以后，提交内容的风格统一率提高非常明显。

另一个典型场景是处理重复性任务。如果你每周都要分析一批服务日志，默认做法是每次手动粘贴日志、手动描述分析要求。配置完日志分析 Agent 之后，我把指令、输出格式、抽样规则全部固化进去。这样触发一次任务，输出结构基本一致，省下的不只是时间，还有反复纠错的成本。

1.3 适合谁用、学完能做什么

我觉得有三类人非常适合折腾自定义 Agent：

• 长期在终端里工作，想把"打开编辑器-复制提示词-粘贴"这套动作彻底省掉的人。
• 对 AI 输出稳定性有要求的团队，希望把个人经验沉淀成团队资产的人。
• 纯粹想把工具吃透的发烧友，这类人通常能挖出很多官方文档都没提到的细节。

学完这套配置方法，你至少能做到：创建属于自己的 Agent、调整它的角色指令和工具权限、在项目目录下加载不同 Agent、定位并解决配置不生效或输出质量差的问题。下面我会把整个链路拆开讲。

2. 自定义 Agent 的核心设计思路

2.1 一个 Agent 配置文件到底包含什么

Kiro CLI 的自定义 Agent 一般由一个独立配置文件承载，常见格式是 YAML。拆开来看，一个配置核心由几部分组成：

把这几个字段理解对，配置就成功了一半。很多人容易犯的错是把所有希望都压在 system prompt 上，看到输出不对劲就拼命加字，完全忽略 tools 和 context 的影响。实际上，工具权限过宽会让 Agent"主动"跑偏，上下文混入大量无关文件会让它注意力涣散。

2.2 角色指令（System Prompt）的写法技巧

写 system prompt 和写普通提示词完全不同。普通提示词是"一次性交互"，你可以随意；但 system prompt 是"长期固定人格"，需要兼顾稳定性、边界和恢复能力。

我常用的写法框架是四段式：

• 身份定义：这个 Agent 是谁，服务对象是谁。
• 任务描述：它主要完成什么类型的任务。
• 工作约束：哪些事绝对不能做，哪些步骤必须走。
• 输出格式：结构化输出的模板，最好给一个例子。

举个例子。如果你在写"日志分析 Agent"，不要只写"你是一个日志分析专家"。要写清楚"你是一个负责服务端日志分析的助手，任务是从传入的日志片段中找出异常链路、定位错误根因、按时间线输出结论。禁止编造日志中不存在的信息，禁止输出与本次日志无关的内容。最终输出必须是：概述、时间线、异常清单、可能原因、建议动作。"

我在实际使用中发现，第四部分给例子比空泛要求有效得多。AI 模型对格式例子的遵从度远高于对抽象描述的理解。所以如果你的配置里还没有一个"输出示例"，建议先补上。

2.3 工具与上下文的绑定逻辑

Kiro CLI 这类 CLI 工具的便利之处在于，它可以直接访问本地文件系统、执行命令、读取 Git 状态。但工具调用是一把双刃剑。“能力”越强，"自由发挥"的空间也越大。比如审查 Agent 只需要读文件、看 diff，那你就不要给它开放写文件或执行命令的权限。给得太多，它可能会擅自修改文件，或者做一些你没要求它做的事。

上下文绑定的逻辑也是同理。不要一股脑把整个项目塞进 context。我看到不少人的配置里 context 包含了全量文件列表，token 消耗巨大，但输出质量并没有变好。正确做法是根据任务精准选择：代码审查就带上最近的 git diff，日志分析就带上指定日志路径，文档写作就带上相关章节的大纲。上下文的质量远比数量重要。

3. 实操：从零配置一个自定义 Agent

3.1 初始化配置目录与首个 Agent

不同版本初始化命令可能略有差异，但思路一致。我在 0.4.x 版本上习惯用kiro agent init来生成配置骨架。执行之后，Kiro CLI 会创建默认配置目录，一般是~/.kiro/agents/。如果目录已存在，它会告诉你当前有哪些 Agent。

初始化完成后，我建议先确认三件事：

• 配置目录是否存在且路径正确。
• 是否生成了示例 Agent 配置，比如example.yaml。
• 输入kiro agent list能否看到这个示例。

这一步看起来简单，但很多人后面配置不生效，回头排查才发现是路径根本没对。在继续往下之前，务必保证kiro agent list能正常列出内容。

3.2 编写一个完整的 Agent 配置（附示例）

下面我给一个完整示例，作用域是一个"代码审查 Agent"。注意这是配置骨架，你需要按自己本地的语法微调。

name: code-reviewer description: 对当前分支的变更进行代码审查，输出问题清单与修改建议 role: | 你是一位资深代码审查员。 请基于当前分支与主干分支的差异进行审查，重点关注潜在缺陷、性能问题、可读性和安全隐患。 禁止修改任何文件，禁止执行 build 或 run 命令。 如果某个文件没有变更，不要评价它。 输出格式为：变更摘要、风险等级、问题列表、每个问题的建议修复方案。 examples: - 输入: kiro code-reviewer 输出: | 变更摘要: ... 风险等级: 中 问题列表: 1. [严重] ... 2. [一般] ... context: - git: diff HEAD~1 - file: README.md tools: - git - grep - cat settings: model: default temperature: 0.2 max_tokens: 4096

这里有几个值得注意的细节：

tools我刻意没有放 write、run 之类的高危工具，就是为了让它安心做审查员。temperature设成 0.2，意图是让输出更稳定、更少发挥。如果是一个创意写作类 Agent，这个值可以调高，但对于代码审查这个场景，稳定就是第一需求。

3.3 加载 Agent 与本地调试

配置完成后，用kiro agent use code-reviewer切换到这个 Agent。之后的对话就会自动携带这个配置里的 role、context 和工具权限。

我第一次配置完，直接在仓库里跑了一下，发现输出没有按预期格式走。这个时候不要急着改 role，先看两样东西：一是 Kiro CLI 的调试日志。多数 CLI 工具都支持--debug或-v参数，它会把你实际发送给模型的完整消息列出来。你一眼就能看出是 role 没有被正确附加，还是 context 没拼进去。二是 token 消耗统计。如果实际消耗远超预期，基本就是 context 部分出了问题。

还有一种更快的验证方式：把配置里的 role、context 复制到普通对话里，去掉 Agent 层，看模型表现如何。如果普通对话里表现好，Agent 加载后表现差，说明是配置加载链路出了问题，而不是提示词本身有问题。

3.4 模型参数与生成策略的调优

这里分享几组我实际的参数经验值：

• temperature 0.0 ~ 0.3：代码生成、代码审查、日志分析、格式转换类任务。
• temperature 0.4 ~ 0.7：文档撰写、技术方案构思、需求拆解类任务。
• temperature 0.8 以上：头脑风暴、别名生成、创意文案，这类任务我不建议配置成正式 Agent 使用。

max_tokens 不是越大越好。它代表的是单次输出上限。如果设置过大，输出容易冗余；如果太小，任务做到一半会被截断。一般代码审查我给 4096，日志分析给 2048，文档写作给 8192。

另外，context window 不要一次性填满。留出至少 30% 的余量给对话过程中产生的中间内容，否则 Agent 会在大约几分钟的对话里丢失早期信息。

4. 实战案例：三个常用 Agent 模板

4.1 代码审查 Agent

代码审查 Agent 是我使用频率最高、回报最大的一个配置。它的核心价值不在“能找到 bug”，而在于能把审查标准稳定下来。一个团队如果靠人工 reviewer，每个人的严格程度不同，但 Agent 的输出结构是固定的，很容易形成公共审查基线。

我的代码审查 Agent 还有一个独特的小设计：在 role 里明确要求"先复述变更意图，再给问题"。这个设计听起来简单，但实际效果非常好。因为模型在输出问题之前先复述一遍代码意图，相当于强制自己做了一次自我检查，很多误报在那一步就被过滤掉了。如果你想让审查结果更准确，可以考虑这个写法。

4.2 日志分析 Agent

日志分析 Agent 的配置与代码审查很不一样。它不需要访问整个项目，只需要指定日志文件路径和输出格式。我的实践是通过命令行传入日志片段，或者用 context 绑定指定日志文件路径，而不是把所有日志全塞进去。

配置要点是把输出格式卡死。我给它的 role 里写死了四条输出顺序：异常时间线、错误类型分布、疑似根因、建议动作。这样每周处理生产日志时，拿到的结果都是同一套结构，可以直接进周报模板。有段时间日志量特别大，完整日志会超上下文窗口。解决方案是在 context 里配置一个"日志抽样"工具，先做降采样再分析，这个思路很有效。

4.3 技术文档写作 Agent

技术文档写作 Agent 是最考验 prompt 功力的配置，因为文档写作的"主观性"最强。你既希望它有专业性，又不希望它写得像营销文案。我的核心做法是在 role 里加上"禁止使用空洞的形容词，优先使用可验证的描述"。

如果你在写 API 文档，就要求每条参数都有名称、类型、默认值、示例。如果你在写故障复盘，就要求格式为"背景、影响、时间线、根因、改进项"。给一个明确的结构模板，生成出来的文档基本可以直接进入 review 流程，只要有这个效果，这个 Agent 就是值得配的。

5. 常见问题与排查技巧实录

5.1 配置加载失败

最常见的问题是路径不对。你可能修改了~/.kiro/agents/里的配置，但 Kiro CLI 实际加载的是项目根目录下的.kiro/agents/。两个目录的配置同名时，到底哪个生效会让人困惑。我在前期就踩过这个坑，改了半天发现改的是另一个文件。

我的排查顺序是：

• 执行kiro agent list，看当前能识别到哪些 Agent。
• 执行kiro agent path（如有该命令）确认当前生效目录。
• 检查文件后缀和语法。YAML 缩进错误是最隐蔽的失败原因。

如果确认是语法问题，很多 CLI 工具会在加载时报错。报错信息里通常会带行号，照着行号检查缩进和冒号后面有没有空格就行。

5.2 指令不生效或输出不符合预期

指令不生效，优先级排查以下三点：

• 你的输出约束与模型默认行为冲突。比如明明要求"不要给开场白"，但模型还是先客套一句。解决办法是在 role 里明确指出"直接输出结果，不要解释"。甚至可以加一句"如果你理解了，不要回复确认，直接开始任务"。
• 上下文太长，role 被稀释。模型对长上下文的注意力分布不是均等的，后面的指令可能被前面大量文件内容覆盖。解决方式是砍掉不必要的 context。
• 对话中出现了与 role 冲突的用户指令。Kiro CLI 的 Agent 模式下，用户在对话里新提出的要求往往优先级更高，这是符合预期的。如果你发现 Agent 突然"失忆"，看看是不是自己的追问把初始角色覆盖掉了。

5.3 工具调用报错

工具调用报错的常见原因有三种：

• 权限不足。配置里声明了某个工具，但 CLI 进程没有访问对应文件或目录的权限。解决方法是用真实账号确认目标路径可读。
• 工具不在白名单。你配置调用了 write，但 tools 列表里没写 write，调用自然失败。
• 工具参数错误。查看调试日志里工具收到的原始参数，自己手动跑一遍同样命令确认是否能复现。

排查工具问题有一条高效路径：开启 debug 模式，把 Agent 传入工具的参数复制出来手动执行。如果手动执行正常但 Agent 调用失败，再看是不是用了绝对路径、路径里有没有空格等容易被转义出问题的字符。

5.4 上下文爆掉与生成变慢

上下文爆掉的表现非常直观：对话一开始还好，过一阵子 Agent 就开始忽略你已经说过的信息，或者出现重复内容。这种情况几乎都是因为 context 配置得太贪婪。

我给的解决方案很简单：

• 给 context 里的文件设置行数或大小上限。
• 日志类数据不要整文件携带，先做抽样。
• 不要一次开太多工具输出。grep 的结果容易特别长，最好在 role 里加一句"使用 grep 时尽量输出文件名和行号，不要输出整行内容"。

生成变慢的另一个原因是 temperature 太高或 max_tokens 过大。这些参数不影响网络传输，但会让模型生成更长的内容，甚至在一些设置下增加重试概率。生成类任务调低 token 上限，体感速度提升明显。

6. 进阶扩展与我的实操体会

6.1 让 Agent 之间互相协作

自定义 Agent 并不只是"单兵作战"，你可以利用 CLI 的管道能力把多个 Agent 串起来。比如我经常用三个 Agent 串成一条链路：先用"日志分析 Agent"把原始日志转成结构化摘要，再用"代码审查 Agent"检查相关代码路径，最后用"文档 Agent"把结论整理成周报文本。

串联的方式不是在一个 Agent 的 role 里强行塞入全部任务，而是让每个 Agent 只负责自己擅长的一段，前一个 Agent 的输出作为后一个 Agent 的输入。这样每个环节的提示词都足够聚焦，任何一个环节出问题都能快速定位和替换。

6.2 把配置纳入版本管理

配置文件就是你的团队资产，值得像代码一样管理。我在团队内部建了一个独立仓库，专门存放所有 Agent 配置。每次调整必须走 review 流程，开一个分支，改完提交，让另一个同事确认 role 的措辞没有歧义。

有人可能会觉得这有点过度工程。但我的经验是，System Prompt 一旦被多人长期使用，它的变更风险并不比核心代码小。你改一个措辞，可能让所有人的输出风格发生变化。不 review 就上线，十次里有八次会有人觉得"哪里怪怪的，但说不出来"。

6.3 我个人踩过的一些坑

最后分享几个零散但很痛的教训：

一个是命名。Agent 的名字不要太泛，比如helper、analyzer。当你配到第五个 Agent，kiro agent list里同时出现code-analyzer和log-analyzer时才明白名字里的冗余只会制造混乱。第二个是别过度堆叠 role。我早期总觉得提示词写得越长越厉害，往一个 Agent 里塞了上千字。结果输出变得呆板，回复前还要先解释自己会怎么做。加了直接开始任务才稍微好转。第三个是定期清理。长期不用的 Agent 果断删掉或归档，配置目录不是仓库，杂物会干扰选择，没必要让它一直留在列表里。

说实话，自定义 Agent 这件事，前两次配置的 ROI 不一定高，因为你需要熟悉语法和打磨措辞。但只要你坚持配到第三个、第四个，后面基本就是一种肌肉记忆。现在我在新项目里第一件事不是去装别的工具，而是把常用的 Agent 配置复制过去，改一改角色描述，项目上下文立刻就位了。这个习惯，帮我省下的碎片时间远比我当初折腾配置投入的时间多。