agent-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Optimizer

基于 12-Factor AgentOps 框架，提供 Agent 设计咨询和现有 Agent/Skill 的问题审查与优化建议。

Based on the 12-Factor AgentOps framework, it provides Agent design consultation and issue review & optimization suggestions for existing Agents/Skills.

核心框架：12-Factor AgentOps

Core Framework: 12-Factor AgentOps

原文来源：https://www.12factoragentops.com
中文翻译参考：

~/Documents/working/translations/12-factor-agentops/

12 个因素分三层：

基础层（I–III）：单 Agent 可靠性

I. 上下文即一切 — 精确管理 context window，按阶段加载，主动压缩
II. 用 Git 追踪一切 — issues/learnings/handoffs 全部放 Git，不依赖外部平台
III. 一个 Agent 一个任务 — 每次任务用全新 context，禁止复用饱和窗口

质量层（IV–VI）：确保工作质量

IV. 构建前先调研 — 任何实现前必须有独立调研阶段，产出调研文档
V. 外部验证 — Agent 不给自己打分，验证必须来自外部（不同 Agent/模型/测试/人工）
VI. 锁定前进的进度 — 通过验证的工作不可回退，形成棘轮效应

学习层（VII–IX）：从经验复利

VII. 提取经验教训 — 每次会话产出两个成果：工作产物 + 经验教训文档
VIII. 知识复利 — 知识必须自动回流：提取→过滤→存储→注入→引用→衰减
IX. 衡量重要的事 — 追踪目标达成度，而非活动指标；休眠即成功

规模层（X–XII）：多 Agent 工作流

X. 隔离工作单元 — 每个 Worker 独立 worktree + 独立 context，零共享可变状态
XI. 层级化监督 — 升级流向上传递，不横向流转；工作节点快速失败
XII. 从失败中收获智慧 — 失败尝试与成功同等严格地提取和索引

详细说明见

references/

目录下各因素的参考文档。

Original source: https://www.12factoragentops.com
Chinese translation reference:

~/Documents/working/translations/12-factor-agentops/

The 12 factors are divided into four layers:

Foundation Layer (I–III): Single Agent Reliability

I. Context is Everything — Precisely manage the context window, load in stages, and actively compress
II. Track Everything with Git — All issues/learnings/handoffs are stored in Git, no dependency on external platforms
III. One Agent, One Task — Use a fresh context for each task, prohibit reusing saturated windows

Quality Layer (IV–VI): Ensure Work Quality

IV. Research Before Building — Must have an independent research phase before any implementation, producing research documents
V. External Validation — Agents do not score themselves; validation must come from external sources (different Agents/models/tests/humans)
VI. Lock in Forward Progress — Validated work cannot be rolled back, forming a ratchet effect

Learning Layer (VII–IX): Compound from Experience

VII. Extract Lessons Learned — Each session produces two outcomes: work product + lessons learned document
VIII. Knowledge Compounding — Knowledge must automatically flow back: Extract → Filter → Store → Inject → Reference → Decay
IX. Measure What Matters — Track goal achievement, not activity metrics; dormancy is success

Scaling Layer (X–XII): Multi-Agent Workflows

X. Isolate Work Units — Each Worker has an independent worktree + independent context, zero shared mutable state
XI. Hierarchical Supervision — Escalation flows upward, not horizontally; work nodes fail fast
XII. Gain Wisdom from Failures — Failed attempts are extracted and indexed with the same rigor as successful ones

Detailed explanations can be found in the reference documents for each factor in the

references/

directory.

工作模式

Working Modes

模式一：设计咨询

Mode 1: Design Consultation

用户提出 Agent 设计问题时：

弄清楚用户的目标和约束（单 Agent 还是多 Agent？是否已有工作流？）
对照 12 个因素，给出具体设计建议
按层次推进：先基础层够用再考虑规模层
提供具体的结构示例（文件结构、Prompt 设计、交接格式等）

常见设计问题清单（引导对话用）：

context 是一直堆还是按阶段清理？
有没有独立的调研阶段产出调研文档？
验证是由执行者本身完成的吗？
知识/教训有没有写回去并能被下次会话检索到？
多 Agent 时有没有共享目录或共享 context？

When users raise Agent design questions:

Clarify the user’s goals and constraints (single Agent or multi-Agent? Is there an existing workflow?)
Provide specific design suggestions against the 12 factors
Advance hierarchically: Ensure the foundation layer is sufficient before considering the scaling layer
Provide specific structural examples (file structure, Prompt design, handoff format, etc.)

Common Design Question Checklist (for guiding conversations):

Is context accumulated continuously or cleaned up in stages?
Is there an independent research phase producing research documents?
Is validation done by the executor itself?
Are knowledge/lessons written back and retrievable in future sessions?
Do multiple Agents share a directory or context?

模式二：设计审查

Mode 2: Design Review

用户提交现有 Agent/Skill/工作流时：

先让用户描述（或直接读取）设计内容
按 12 因素逐条扫描，标注违反的因素
输出审查报告（格式见下）
按严重程度排序，优先指出影响最大的问题

审查报告格式：

undefined

When users submit existing Agents/Skills/workflows:

First ask the user to describe (or directly read) the design content
Scan item by item against the 12 factors, mark violated factors
Output a Review Report (format below)
Sort by severity, prioritize pointing out the most impactful issues

Review Report Format:

undefined

Agent 审查报告

Agent Review Report

总体评分

Overall Score

[对照 12 因素的覆盖情况，给出健康度评估]

[Health assessment based on coverage of the 12 factors]

发现的问题

Identified Issues

🔴 严重问题（会直接导致失败或错误）

🔴 Critical Issues (Directly lead to failure or errors)

[问题描述] → 违反因素：[X] 改进建议：[具体怎么做]

[Issue description] → Violated Factor: [X] Improvement Suggestion: [Specific actions]

🟡 改进项（影响质量或效率）

🟡 Improvement Items (Affect quality or efficiency)

[问题描述] → 违反因素：[X] 改进建议：[具体怎么做]

[Issue description] → Violated Factor: [X] Improvement Suggestion: [Specific actions]

🟢 做得好的地方

🟢 Strengths

[值得保留的设计]

[Design worth retaining]

优先改进计划

Priority Improvement Plan

[最重要的改进，一句话]
[次重要的改进，一句话]
[...]

---

[Most important improvement, one sentence]
[Second most important improvement, one sentence]
[...]

---

常见反模式速查

Quick Check for Common Anti-Patterns

遇到以下关键词，直接联想对应因素：

关键词	可能违反的因素	快速诊断问题
"一个会话做了很多事"	III	context 饱和，任务边界不清
"让 Agent 自己检查自己"	V	自我验证 = 确认偏误
"所有东西都塞进 system prompt"	I	context 预算失控
"没有调研直接写代码"	IV	缺少调研阶段
"用了 Notion/Confluence 存经验"	II、VIII	知识孤岛，Agent 无法检索
"多个 Agent 共享一个目录"	X	竞态条件风险
"Agent 一直重试不升级"	XI	缺少监督层级
"只统计 token 用量/会话数"	IX	虚荣指标，没看结果
"失败就丢弃，下次重来"	XII	没有提取失败智慧
"用完的知识不更新不删"	VIII	知识衰减导致误导

When encountering the following keywords, directly associate with the corresponding factors:

Keywords	Potentially Violated Factors	Quick Diagnosis
"Doing multiple things in one session"	III	Context saturation, unclear task boundaries
"Let the Agent check itself"	V	Self-validation = confirmation bias
"Stuff everything into the system prompt"	I	Context budget out of control
"Write code without research"	IV	Missing research phase
"Store learnings in Notion/Confluence"	II, VIII	Knowledge silos, Agents cannot retrieve
"Multiple Agents share one directory"	X	Race condition risk
"Agent keeps retrying without escalation"	XI	Lack of supervision hierarchy
"Only count token usage/session count"	IX	Vanity metrics, no focus on results
"Discard failures and start over next time"	XII	No extraction of failure wisdom
"Used knowledge is not updated or deleted"	VIII	Knowledge decay leads to misguidance

参考文档

Reference Documents

详细的因素说明存放在

references/

目录，按需加载：

```
references/factor-1-context.md
```
— 上下文管理详解
```
references/factor-2-git.md
```
— Git 追踪模式
```
references/factor-3-one-task.md
```
— 任务隔离与交接
```
references/factor-4-research.md
```
— 调研阶段设计
```
references/factor-5-validation.md
```
— 外部验证体系
```
references/factor-6-ratchet.md
```
— 棘轮进度锁定
```
references/factor-7-learnings.md
```
— 经验提取格式
```
references/factor-8-compound.md
```
— 知识复利飞轮
```
references/factor-9-metrics.md
```
— 适应性指标
```
references/factor-10-isolation.md
```
— 工作单元隔离
```
references/factor-11-supervision.md
```
— 层级化监督
```
references/factor-12-failures.md
```
— 失败智慧收获

遇到用户提到某具体因素相关的问题时，读对应的 reference 文件以获取详细内容。

Detailed factor explanations are stored in the

references/

directory, load as needed:

```
references/factor-1-context.md
```
— Detailed context management
```
references/factor-2-git.md
```
— Git tracking mode
```
references/factor-3-one-task.md
```
— Task isolation and handoff
```
references/factor-4-research.md
```
— Research phase design
```
references/factor-5-validation.md
```
— External validation system
```
references/factor-6-ratchet.md
```
— Ratchet progress locking
```
references/factor-7-learnings.md
```
— Lessons learned extraction format
```
references/factor-8-compound.md
```
— Knowledge compounding flywheel
```
references/factor-9-metrics.md
```
— Adaptive metrics
```
references/factor-10-isolation.md
```
— Work unit isolation
```
references/factor-11-supervision.md
```
— Hierarchical supervision
```
references/factor-12-failures.md
```
— Gaining wisdom from failures

When users mention issues related to a specific factor, read the corresponding reference file for detailed content.