technical-writing

技术写作技能

概述

撰写关于你正在构建的功能的技术博客文章。此技能会分析你的代码库以了解实现方式，然后组织清晰、引人入胜的内容，在技术细节与可读性之间取得平衡，同时避免使用听起来像 AI 写的语言。

流程

阶段 1：研究与规划

1.1 加载写作指南（必需 — 首先加载）

开始任何其他工作之前，先加载以下内容：

1. 写作规则（读取 WRITING_ANTI_PATTERNS_PATH 环境变量指定的文件；若未设置，则使用 references/anti-patterns.md）——其中列有应避免的、听起来像 AI 写的词语、短语和模式。这是基础：明确哪些表达方式要避免。

2. 写作风格指南（读取 WRITING_STYLE_GUIDE_PATH 环境变量指定的文件；若未设置，则使用 references/style-guide.md）——其中介绍个人写作风格、语气、结构和标志性手法。这是声音层：明确应该呈现怎样的表达风格。

优先级规则：如果指南之间存在冲突，以反模式规则为准。避免 AI 风格始终优先于风格选择。

1.2 获取 WordPress 分类法（如果已配置）

如果设置了 WORDPRESS_URL、WORDPRESS_USERNAME 和 WORDPRESS_APP_PASSWORD 环境变量，请在写作前获取可用的分类和标签，以便 frontmatter 使用已有的分类法：

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"

选择 frontmatter 中的 category 和 tags 时，请使用这些值。优先选择已有值。如果未设置 WordPress 环境变量，则跳过此步骤。

1.3 了解已构建的内容

调查代码库以了解该功能：

• 询问对方想要介绍哪个功能或变更
• 如有必要，使用 git 查看近期提交（如果不是 git 仓库，则跳过）：git log --oneline -10
• 阅读相关代码文件，了解实现方式
• 确定关键技术决策、架构和有趣的细节
• 记录已解决的难题或巧妙的解决方案

1.4 规划结构

规划文章要涵盖的内容。以下内容仅供参考，不是固定模板：

• 开篇：以引人入胜的切入点或所构建内容的背景开场
• 概述：用 2-3 句话简要说明该功能
• 问题／价值：说明其重要性或解决的问题
• 技术细节：通过代码片段说明其工作原理
  • 关键实现细节
  • 有趣的技术决策
  • 使用的架构或设计模式
• 挑战：遇到的难题及其解决方式（如适用）
• 未来计划：后续步骤或相关功能（如适用）
• 技术栈：使用的技术（可融入叙述，也可列出）

实际的标题、结构和行文应自然贴合具体文章，而非拘泥于固定格式。

阶段 2：撰写

2.1 起草

运用你在阶段 1 中加载的两份指南撰写博客文章。完成初稿后，对照反模式指南重新审阅文章，并修正所有违规之处，然后保存。

代码片段：

• 代码片段应简短（5-15 行）

目标篇幅：根据复杂程度调整。默认写短一些。

• 简单想法、公告或单一概念：400-600 字
• 中等难度的技术演练：600-900 字
• 深入的架构解析或多部分说明：900-1200 字

宁可写短一些。如果 500 字就能说清楚，就不要扩写到 800 字。删掉填充内容，合并单薄的章节，在表达清楚要点后就收笔。

2.2 保存草稿

将完成的博客文章保存到草稿目录（如果目录不存在，则创建它）。

查找保存路径，运行：echo $WRITING_DRAFTS_PATH

• 如果输出不为空，则保存到该路径
• 如果为空，则保存到当前项目中的 .drafts/

文件命名约定：

• 格式：YYYY-MM-DD-slug.md
• slug 应简短、易记、易输入，最多两个单词
• 概括文章的核心概念，不一定要和标题一致
• 想想“访问域名后，我会输入什么？”
• 示例：2025-12-29-ralph.md（文章标题：“How I Got Ralph to Ship Overnight”）、2026-01-10-listen.md（文章标题：“Giving my blog a voice”）、2025-11-15-choosing-open.md（文章标题：“WordPress Almost Didn't Happen”，主题是选择开源）

Frontmatter（必填）：

每篇草稿都必须以包含 title 和 url 的 YAML frontmatter 开头：

---
title: How I got Ralph to ship overnight
url: /ralph
category: Development
tags:
  - AI
  - Shipping
---

• title —— 文章标题（正文中不要重复使用 H1 标题）。标题应简短（3-7 个单词）、引人入胜，并留有好奇空间。不要解释整篇文章，只需暗示主题。想象报纸标题，而不是说明文。
  • 好例子：“Giving my blog a voice”、“WordPress Almost Didn't Happen”、“Planning Out Loud”
  • 坏例子：“I built a skill that writes blog posts from my codebase”（太长，把所有内容都解释清楚了）
• url —— 永久链接路径，应与文件名中的 slug 一致（例如 /ralph、/listen、/choosing-open）
• category —— WordPress 分类（如有，请使用阶段 1.2 中已有的分类）
• tags —— WordPress 标签（优先使用阶段 1.2 中已有的标签）

阶段 3：发布（可选）

3.1 发布到 WordPress

如果用户想发布到 WordPress，请加载 WordPress 发布指南（references/wordpress-publishing.md），获取完整的设置和发布说明。

该指南涵盖：

• 环境设置和凭据
• Python 依赖项安装
• 发布命令和工作流
• 智能更新跟踪（避免重复发布文章）
• 常见问题排查

快速概览：

• 首次发布：创建新的 WordPress 草稿
• 后续发布：更新现有草稿（不会重复创建）
• 始终保存为草稿（绝不会自动发布）
• 返回文章 URL 和编辑 URL

输出格式

创建并保存博客文章后，请提供：

1. 保存位置：文章的保存路径
2. 文章标题：最终使用的标题
3. 引用的关键文件：列出提及的文件及其行号
4. 字数：大致篇幅

交互示例

用户：“帮我写一篇关于语音规划功能的文章”

回复：

Let me investigate the voice planning implementation to write about it.

[Phase 1: Loads anti-patterns + style guide, fetches WP taxonomy, reads code]

[Phase 2: Creates and saves blog post applying both guides]

Blog post saved to: .drafts/2025-12-29-planning-aloud.md

Title: "Planning Out Loud"

Key Files Referenced:
- src/components/voice-session.tsx:78 (voice session initialization)
- src/app/api/webhook/route.ts:40 (webhook signature validation)
- src/lib/claude.ts:88 (Claude tool calling)

Word Count: ~550 words

环境变量

在 Claude Code 设置（~/.claude/settings.json）的 env 键下进行配置：

{
  "env": {
    "WRITING_STYLE_GUIDE_PATH": "/path/to/style-guide.md",
    "WRITING_ANTI_PATTERNS_PATH": "/path/to/anti-patterns.md",
    "WRITING_DRAFTS_PATH": "/path/to/drafts",
    "WORDPRESS_URL": "https://yourblog.com",
    "WORDPRESS_USERNAME": "your_username",
    "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx",
    "WRITING_TITLE_CASE_STYLE": "title",
    "WRITING_HEADING_CASE_STYLE": "sentence"
  }
}

变量	必填	描述
WRITING_STYLE_GUIDE_PATH	否	共享写作风格指南的路径。在第 1.1 阶段加载
WRITING_ANTI_PATTERNS_PATH	否	共享反模式的路径。会覆盖 references/anti-patterns.md
WRITING_DRAFTS_PATH	否	草稿保存位置。默认使用当前项目中的 .drafts/
WORDPRESS_URL	发布时必填	WordPress 站点 URL（包含 https://）
WORDPRESS_USERNAME	发布时必填	WordPress 账户用户名
WORDPRESS_APP_PASSWORD	发布时必填	应用程序密码（不是常规密码）
WRITING_TITLE_CASE_STYLE	否	"sentence"（默认）或 "title"
WRITING_HEADING_CASE_STYLE	否	"sentence"（默认）或 "title"

获得最佳效果的提示

1. 明确范围：“撰写有关 webhook 安全实现的内容”优于“撰写有关 webhook 的内容”
2. 说明目标受众：“面向熟悉 Next.js 的开发者”与“面向非技术读者”
3. 指定偏好的篇幅：“简短的 500 字更新”与“详尽的深入分析”
4. 提供背景信息：“这是系列文章的第 2 篇”或“这是关于该项目的第一篇文章”
5. 提出修改要求：初稿完成后，可要求扩展章节、简化说明或调整语气

进阶：系列文章

对于多篇系列文章：

• 先说“帮我为关于 [主题] 的 3 篇系列文章列出大纲”
• 每篇文章都应基于上一篇的内容展开
• 加入“前情回顾”和“接下来”部分
• 保持各篇文章的结构一致