从写作风格指南到一键触发 —— 一个 doc-writer Agent 的诞生

问题起点

开发笔记的核心价值是沉淀可复用的经验——记录"下次遇到类似问题该怎么想"，而非流水账式的"做了什么"。

但写笔记本身有成本：回顾问题现象、梳理排查路径、提炼根因和方案，还要确保输出符合个人的写作习惯。当用 AI 辅助写作时，问题更明显。我用一个实际场景测试：

输入： “帮我写份 WS2812 PWM+DMA 驱动的调试笔记”

输出：

## 背景
## 目标
## 实现步骤
## 总结

这是典型的模板化输出——结构有了，但风格不对。我的写作习惯是从问题现象切入，按"撞墙→找墙→拆墙"的叙事展开，而不是填空式的"背景-目标-步骤-总结"。

核心问题：模板只能规定结构，无法内化风格。 需要的是一个能理解"我怎么写"的工具。

方案对比

四种可行方案的利弊分析：

方案	优点	缺点
每次给写作指令	灵活	重复劳动，指令过长容易遗漏
使用模板	结构清晰	输出千篇一律，无个人风格
写 Skill	内化原则	与当前会话共享上下文，无法隔离
Agent + Command	上下文隔离、模型可选、一键触发	需要额外配置

选择方案四。设计目标：一键触发，独立上下文，按我的风格输出。

核心设计：原则驱动，而非模板驱动

关键设计决策：不使用模板，而是内化原则。

基于 7 个会话记录、6 份开发文档、1 篇博客稿的风格分析，提炼出六条写作原则：

原则	含义
问题驱动，现象先行	从"遇到了什么"切入，非"背景知识"开篇
证据说话，代码为证	结论需有代码/日志/配置支撑
经验提炼，非流水账	记录"下次该怎么想"，非"做了什么"
结构分层，逻辑递进	每个子问题内部是完整推理链
真诚直白，拒绝套话	不写"众所周知"，不粉饰难度
完整回顾，记录过程	失败尝试与成功方案同等重要

两条流程设计：

1. 先大纲后展开 — 确认方向再动笔，避免写完大改
2. 模型选择 — 写作任务用 haiku，成本优化

这两条设计对应一个核心认知：让 AI 先思考结构，再填充内容。

一个具体的例子：doc-writer Agent 本身

为了说明这套方法，我拿刚才开发的 doc-writer Agent 作为例子。

Agent 文件 (~/.claude/agents/doc-writer.md) 的核心结构：

---
name: doc-writer
description: 技术文档与开发日志撰写专家...
tools: ["Read", "Write", "Edit", "Grep", "Glob"]
model: haiku
---

# 文档撰写助手

## 六条核心原则
[原则内容...]

## 两种写作模式
### /doc note — 开发笔记模式
### /doc blog — 技术博客模式

## 工作流程
1. 接收模式与主题
2. 回顾上下文
3. 生成大纲/叙事线索
4. 展开写作
5. 保存文档

## 默认保存位置
[自动查找 Doc/ 或 docs/ 目录...]

Command 文件 (~/.claude/commands/doc.md) 的核心结构：

---
description: 触发 doc-writer Agent...
---

# /doc - 技术文档撰写

## 用法
/doc note [主题]     # 开发笔记模式
/doc blog [主题]     # 技术博客模式

## 模式说明
[两种模式的区别...]

## 默认保存位置
[自动查找逻辑...]

使用时只需要：

/doc note WS2812调试

Agent 会自动：

1. 回顾当前会话上下文
2. 提取问题解决的完整过程
3. 先给我大纲确认
4. 确认后展开撰写
5. 保存到项目的 Doc/ 目录

现状：Agent 尚未完善。 测试时发现新创建的 Agent 需要重启会话才能生效。实际输出的风格匹配度，需要在真实场景中验证和迭代。

迭代实例：风格修正

这篇文章本身就是一次迭代过程。初稿完成后，我发现开篇部分过于口语化：

初稿片段：

我写了很多开发笔记。每次调试完一个棘手的问题，我都想把过程记录下来……但写笔记这件事本身就很累。我得回忆刚才遇到了什么问题……更累的是，每次都要重新组织语言……

问题分析：

问题类型	具体表现
情绪化表达	“很累”“很烦”
口语叙述	“有一次，我刚调完……”
模糊结论	“我不知道”“也许”

修正策略：

1. 删除主观情绪，保留客观描述
2. 用表格对比替代口语叙述
3. 结论明确化，不用模糊表达
4. 保持工程师式的冷静客观

修正后：

开发笔记的核心价值是沉淀可复用的经验——记录"下次遇到类似问题该怎么想"，而非流水账式的"做了什么"。

但写笔记本身有成本：回顾问题现象、梳理排查路径、提炼根因和方案，还要确保输出符合个人的写作习惯。

这个修改过程恰好验证了一个观点：风格匹配需要真实场景验证。 即使有六条原则作为指导，初稿仍然偏离了预期风格。Agent 的有效性必须在实际使用中逐步校准。

可迁移的认知

三条设计原则：

1. 让 AI 用你的方式写，而不是替你写。 标准化输出缺少个人风格，将"我怎么写"提炼成原则并内化到 Agent，输出更贴近预期。

2. 提炼原则 > 堆砌模板。 模板规定"填什么"，原则指导"怎么想"。模板无法覆盖边界场景，原则可以迁移。

3. 在合适的节点让人确认。 "先大纲后展开"的设计让人在正确的位置介入——确认方向再执行，避免写完大改。

---

Agent 需要在真实场景中迭代。 这篇博客本身就是迭代过程的记录。等到 doc-writer 迭代若干版本后，才能验证它是否真正内化了写作风格。

Agent 不是一次性做完美的产品，而是边用边改的工具。