# Tech Blog

> 产出中文技术博客，重点解释工具/库/框架/技术路线背后的设计动机与哲学，而不只是功能说明。适用于“写一篇关于 X 的技术博客”“介绍 X 的设计思想”“解释 X 为什么这样设计”等请求。

- Skill: `justcyl/tech-blog` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add justcyl/tech-blog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justcyl/tech-blog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: justcyl (https://skillmd.com/u/justcyl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justcyl/tech-blog

---


# Tech Blog Writer

产出一篇中文技术博客，回答“它为什么存在、为什么这样设计”，而不是停留在“它能做什么”。

## 工作流

### 1. 研究阶段

在动笔前，先建立对项目的深入理解：

- **克隆或直接阅读源码。** 不要只看 README；需要读核心模块、梳理关键数据流、定位结构里隐含的设计决策。
- **阅读可获得的文档**（architecture、design、contributing、AGENTS.md 等）。
- **找出“一个核心思想（one big idea）”**：优秀项目通常在某个核心张力上，给出区别于主流方案的解法。
- **收集 4-6 段代码证据**：优先短小、自包含、能体现设计取舍的函数；避免模板化样板代码。

### 2. 找到对照面

文章必须有显式或隐式的**比较锚点**：

- 主流方案通常如何解决这个问题？
- 该工具哪里不一样？背后体现了什么取舍？
- 不要写泛泛的“Tool A vs Tool B”表格；应聚焦一个具体设计决策点，展示双方处理方式的差异。

示例框架：
- “多数 agent 用滑窗管理上下文，X 选择 append-only tape。”
- “多数框架提供 DSL，X 坚持 plain Python。”
- “多数 CLI 会猜你想做什么，X 要求显式前缀字符。”

### 3. 写作阶段

先阅读 [references/example-pi-post.md](references/example-pi-post.md) 作为黄金样例。重点学习：如何以个人经验切入、如何在叙述中自然植入对照、如何让代码片段承担论据角色。

随后遵循 [references/style-guide.md](references/style-guide.md) 的结构与风格规则。

关键规则：
- **全文中文。** 代码注释可保留英文；术语保留英文原词并补充中文语境。
- **第一人称，技术向对话体。** 不写成学术论文，也不写成口语闲聊。
- **先给代码，再做解释。** 代码是证据，文字是论证。
- **每一节都服务于 one big idea。** 无法回扣核心思想的段落直接删掉。
- **区分项目原话与作者推断。** 项目明确表达的内容要引用或注明来源；自行推断必须明确标注“这是我的判断”。

### 4. 交付前自检

在输出最终文章前逐项检查：
- 所有代码片段都来自真实源码，没有臆造示例。
- 前 3 段内能让读者明确感知 one big idea。
- 存在具体、可验证的主流方案对照。
- 没接触过该工具的读者也能理解“它做什么”和“它为何这么做”。
- 项目陈述与个人分析边界清晰。