blog-writing-specialist

博客写作专家

工作区上下文

提问前先阅读引导上下文：strategy/brand.md 了解品牌、受众、产品、渠道、工具、限制和指标；about/me.md 了解个人风格；content/ideas.md 和 content/calendar.md 了解内容规划。仅在必要时将旧版产品营销上下文文件用作备用。将生成的草稿保存到 content/<platform>/drafts/YYYY-MM-DD_short-topic-slug.md，并将可长期使用的经验反馈到 strategy/brand.md、about/me.md 或 content/ideas.md。

工作约定

此技能对其前置元数据所涵盖的范围是自包含的：将其本地说明、参考资料、脚本和资源用作操作指南；仅询问缺失的任务特定信息；将超出范围的工作交接给相邻技能；并交付可执行的成果、决策、计划、草稿或诊断。

全面的博客写作，融合技术深度、个人风格转换和 AEO 优化。

快速决策树

默认采用用户在 about/me.md 中的工作区风格。仅当用户明确要求使用以下旧版风格，或随附的参考文件明显适用于当前项目时，才使用这些风格。

输入类型	使用章节
技术教程、深入解析、基准测试	技术博客写作
原始想法 → 润色后的文章	技术博客写作 + 工作区风格；仅在用户要求时使用 Nick Nisi 风格
个人风格要求	默认使用 about/me.md；仅在用户要求时使用 Jarad 风格
公司／产品／技术类别文章	根据 strategy/brand.md 调整类别体系
不确定	从这里开始，再按需调整

---

第 1 部分：技术博客写作

撰写面向开发者的技术博客文章。

文章类型

1. 教程／操作指南

分步骤指导读者构建某个东西。

Structure:
1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (GitHub link)
7. Next steps / extensions

规则	原因
先展示最终结果	让读者知道是否值得继续阅读
明确列出前置条件	不浪费不适合的受众的时间
每个代码块都应可运行	以能否复制、粘贴并运行来检验
解释“为什么”，不只讲“怎么做”	解释原理的教程更容易被分享
包含错误处理	实际代码会遇到错误
链接到完整代码仓库	便于读者在教程后查阅

2. 深入解析／说明

深入讲解概念、技术或架构决策。

Structure:
1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading

3. 复盘／事件报告

说明出了什么问题、原因是什么，以及采取了哪些修复措施。

Structure:
1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned

4. 基准测试／比较

基于数据比较工具、方法或架构。

Structure:
1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions

5. 架构／系统设计

说明系统如何构建，以及做出这些决策的原因。

Structure:
1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons

面向开发者的写作规则

风格与语气

应该	不应该
直截了当：“使用连接池”	“你或许可以考虑使用……”
坦承取舍：“这会增加复杂度”	假装自己的方案完美无缺
用“我们”描述团队决策	“我一手设计了整个架构……”
提供具体数字：“将 p99 从 800ms 降至 90ms”	“显著提升了性能”
引用来源和基准测试	提出没有来源的说法
承认存在其他方案	假装自己的方案是唯一选择

开发者反感的内容

❌ "In today's fast-paced world of technology..." (filler)
❌ "As we all know..." (if we all know, why writing it?)
❌ "Simply do X" (nothing is simple if reading a tutorial)
❌ "It's easy to..." (dismissive of reader's experience)
❌ "Obviously..." (if obvious, don't write it)
❌ Marketing language in technical content
❌ Burying the lede under 3 paragraphs of context

代码示例

规则	原因
每个代码块都必须可运行	有问题的示例会摧毁信任
展示完整、可用的示例	缺少上下文的代码片段毫无用处
在围栏代码块中注明语言标识符	语法高亮
在代码后展示输出／结果	让读者验证理解是否正确
使用真实的变量名	用 calculateTotalRevenue，而不是 foo
在示例中加入错误处理	实际代码会处理错误
固定依赖项版本	写“适用于 React 18.2”，而不是“适用于 React”

解释深度

受众信号	深度
“Getting started with X”	解释所有内容，假设读者没有任何相关知识
“Advanced X patterns”	略过基础内容，深入探讨细节
“X vs Y”	假设读者熟悉两者，重点介绍差异
“How we built X”	面向技术读者，可略过基础知识

在开头明确说明你假设的受众水平。

博客文章结构

理想结构

# Title (contains primary keyword, states outcome)

[Hero image or diagram]

**TL;DR:** [2-3 sentence summary with key takeaway]

## The Problem / Why This Matters
[Set up why the reader should care — specific, not generic]

## The Solution / How We Did It
[Core content — code, architecture, explanation]

### Step 1: [First thing]
[Explanation + code + output]

### Step 2: [Second thing]
[Explanation + code + output]

## Results
[Numbers, benchmarks, outcomes — be specific]

## Trade-offs and Limitations
[Honest about downsides — builds trust]

## Conclusion
[Key takeaway + what to do next]

## Further Reading
[3-5 relevant links]

不同类型的字数

类型	字数	原因
快速技巧	500-800	一个概念，一个示例
教程	1,500-3,000	分步讲解需要足够细节
深入探讨	2,000-4,000	全面深入地探索
架构文章	2,000-3,500	图表承担部分说明工作
基准测试	1,500-2,500	数据和图表发挥主要作用

---

第 2 部分：思路倾泻 → 润色后的文章

将杂乱无章的思路倾泻整理成润色后的博客文章。

流程

1. 接收思路倾泻

接受任何形式的内容：

• 零散的想法和观点
• 需要涵盖的技术要点
• 代码示例或命令
• 结论或要点
• 参考链接
• 随机观察

无需事先整理。杂乱的内容就是输入。

2. 了解声音与语气

先阅读 about/me.md，并匹配其中的表达风格。如果用户明确要求使用 Nick Nisi 的风格，请加载 references/voice-tone.md，并遵循下方的指导。

主要特点：

• 对话式表达，同时内容充实
• 坦诚真实，展现脆弱的一面
• 以历程为主线的叙述
• 长短句交替使用
• 具体示例和真实细节
• 有自知之明的幽默

3. 检查故事潜力

阅读 references/story-circle.md，了解叙事框架。

判断内容是否适合采用故事结构：

• 是否呈现了从一种认知到另一种认知的历程？
• 是否能找出问题和解决方案？
• 是否遵循“安逸 → 变故 → 带着变化归来”的结构？

4. 组织内容

将素材整理成以下章节：

常见结构：

• 问题／经历 → 历程 → 结果 → 经验教训
• 准备 → 挑战 → 发现 → 应用
• 理念 → 操作指南 → 反思
• 当前状态 → 过去 → 学习 → 未来

5. 以选定的风格撰写

开篇：

• 以当前处境或近期事件作为引子
• 设置悬念或提出问题
• 坦率直接

正文：

• 灵活调整段落长度
• 用短段落强调重点
• 加入具体细节（工具名称、命令、数字）
• 适当展现脆弱的一面
• 自然地使用行内代码格式
• 使用标题划分内容

技术内容：

• 假设读者具备相关知识，必要时再做说明
• 展示实际命令和示例
• 坦诚说明局限性
• 随意提及工具

结尾：

• 呼应开篇
• 展望未来
• 提供可执行的建议
• 以乐观或发人深省的内容收尾

---

第 3 部分：Jarad 的风格

具有鲜明个人风格的博客写作。

只有在用户明确要求使用 Jarad 的风格，或项目背景表明 Jarad 是作者时，才使用本节。否则，请使用 about/me.md。

核心语气模式

句子结构：

• 富有成效的絮叨：句子较长、曲折，层层补充背景信息
• 在思路展开时提前回应怀疑者，打破第四面墙
• 即使提出宽泛的主张，也加入具体的技术背景
• 示例：“……好吧，如果你非要纠结我的估算准不准确，那我就用 T 恤尺码来代替小时／周数——我很清楚，在 Agent 出现前后这两个时代里，都没有什么有意义的估算——但我想说的是，进步显然惊人，几乎超乎寻常……”

具体而非抽象：

• 描述具体行动：“每天早上翻遍 GitHub”，而不是“突破边界”
• 点名具体工具／人物：“Matt Wolfe、MattVidPro、Claude”，而不是“热门 YouTube 博主”
• 使用鲜明的个人类比：“老板盯着你工作”，而不是“孵化阶段”
• 展现业内人的了解：“GitHub 动态 > YouTube 热度”

语气要素：

• 直率，甚至略带对抗：“动动脑子，自己筛选”
• 即使面对失败，也关注数据：“数据就是数据”
• 带点阴暗的利己角度：“把炸药藏进我们的末日地堡”
• 对夸张说法保持自知：在批评者指出之前，先承认措辞不够精确

绝不要使用：

• “这不是 X，而是 Y”这种听起来深刻的句式
• 陈词滥调式的过渡语：“关键来了”“有趣的地方来了”
• 不带细节的抽象动作动词：“反复尝试”“突破边界”
• 过度润色的博客腔
• 干净利落、解释性强的比喻，例如“孵化阶段”

标题风格：

• 极简：最多 2～4 个词
• 连起来读时，标题本身能讲出故事
• 不加解释性副标题
• 示例顺序：“平坦的图表” → “实验室” → “2024 年春” → “数字” → “窗口期”

内容策略

开头：

• 直接回应怀疑者的问题
• 不要刻意耍聪明——直接复述对方的说法

正文：

• 分享带有具体细节的个人经历
• 打破第四面墙，提前回应批评
• 点名工具、人物和社区，展现自己身处其中
• 需要补充细节时，句子可以放长
• 在絮叨中穿插实用建议

回应批评者：

• 放在段落中间，而不是单独写成辩解部分
• 在别人攻击之前，先自嘲承认
• 然后转回真正想说的重点

结尾：

• 直接回扣开头的问题
• 坦诚谈论自身利益和黑暗未来
• 以有人情味、不那么完美的方式收尾

示例

错误：“那些粗制滥造的软件并没有消失。它们只是在孵化。” 正确：“我觉得更准确的说法是‘孵化阶段’。副作用包括大量垃圾代码，以及长时间沉浸于理论的周期——那些通常写在教科书里的内容，只不过我们还没把它们写出来。”

错误：“我每周都会迎来这些惊人的‘顿悟时刻’。” 正确：“我那阵子势头正猛，没日没夜地做东西——真的是字面意义上的没日没夜，因为我已经很少睡觉了。”

错误：“不断尝试。突破边界。试着搞坏东西。” 正确：“大家都忙着嘲笑 Claude 糟糕的幽默感时，我把每一次失败都看作进步。数据就是数据。大家都在追捧 Matt Wolfe 或 MattVidPro 提到的工具时，我每天早上把鱼线抛进 GitHub 的大海，摸清社区的动向——你猜怎么着——还有多得多的低调开发者，他们不靠 YouTube 曝光，做工具的速度却快了 10 倍。动动脑子，自己筛选。”

---

第 4 部分：分类感知型 AEO 系统（Lightfast）

创建具备分类感知能力、针对 AEO 优化的博客文章。

关键原则：准确性胜过营销

动笔前：

1. 核实每一项说法：

   • 如果引用数字，请确认来源
   • 如果提及某项功能，请确认它已在生产环境中提供
   • 如果不确定，请寻求澄清

2. 切勿夸大宣传：

   • 说明局限性：“目前支持 X；Y 将在 vZ 中推出”
   • 如实说明测试版状态和推出时间表

3. 符合类别语气：

   • 技术：权威、以数据为依据
   • 公司：有远见、定义品类
   • 产品：解决问题、突出收益

类别选择

类别	适用场景	受众
技术	技术深入探讨、架构、研究	开发者、工程师
公司	融资、合作、活动、招聘	高管、投资者
产品	功能发布、更新、教程	客户、潜在客户

写作指南

1. 简洁易读：遵循相应类别的字数要求
2. 先讲价值：从读者能获得什么开始
3. 保持透明：说明测试版状态和局限性
4. 使用主动语态：“你现在可以……”而不是“用户能够……”
5. 不使用表情符号：保持专业语气
6. 包含 TL;DR：为 AI 引用撰写 80–100 个词
7. FAQ 部分：包含 3–5 个符合搜索查询的问题
8. 代码示例：技术类文章必须提供

必需的 Frontmatter

每份草稿都必须包含：

• title、slug、publishedAt、category（核心字段）
• excerpt、tldr（AEO）
• seo.metaDescription、seo.focusKeyword（SEO）
• _internal.status、_internal.generated（可追溯性）

---

第 5 部分：图表生成

何时使用图表

场景	图表类型
请求流程	时序图
系统架构	方框与箭头图
决策逻辑	流程图
数据模型	ER 图
性能比较	柱状图／折线图
前后对比	并排对比图

架构图和基准测试可视化：

使用图表工具（Mermaid、Excalidraw、draw.io）绘制架构图，使用绘图库（matplotlib、Chart.js）制作基准测试可视化。这些工具提供更好的控制，可自托管，并能避免第三方执行风险。

---

第 6 部分：分发

开发者在哪里阅读

平台	格式	发布方式
你的博客	完整文章	首选——掌控自己的内容
Dev.to	交叉发布（规范 URL 指回你的博客）	导入 Markdown
Hashnode	交叉发布（规范 URL）	导入 Markdown
Hacker News	提交链接	项目使用 Show HN，故事使用 Tell HN
Reddit（r/programming、r/webdev 等）	链接或讨论	遵守子版块规则
Twitter/X	主题帖摘要 + 链接	参见 social-media-management 技能
LinkedIn	改编版本 + 链接	参见 linkedin 技能

---

常见错误

错误	问题	修正方法
没有 TL;DR	忙碌的开发者还没看到重点就离开了	在顶部添加 2–3 句摘要
代码示例有误	严重损害所有可信度	发布前测试每个代码块
未指定版本	代码在 6 个月后失效	“适用于 Node 20、React 18.2”
“只需执行 X”	显得轻率且居高临下	删除“只需”“仅仅”“轻松地”等措辞
架构没有图表	用大段文字描述系统	一张图胜过 500 个词
营销腔调	开发者会立即失去兴趣	直接、专业、诚实
没有权衡取舍部分	读起来像有偏见的营销内容	始终讨论缺点
正文前的引言过长	读者会离开	用 2–3 段直入主题
依赖项未固定版本	教程会让未来的读者无法使用	固定版本，并注明撰写日期
没有“延伸阅读”	内容没有后续，也缺乏背景	添加 3–5 个链接，帮助读者深入了解

---

随附资源

参考资料

• references/voice-tone.md - 完整的 Nick Nisi 语气与风格指南
• references/story-circle.md - Story Circle 叙事框架

用法

在使用特定风格写作时，加载参考文件：

• Nick Nisi 风格 → 阅读 references/voice-tone.md + references/story-circle.md
• Jarad 风格 → 使用 Part 3 指南
• 技术写作 → 使用 Part 1 和 Part 2
• 根据类别调整 → 使用 Part 4