peri: Skill for Claude Code

Peri 博客写作风格指南

基于 docs/blogs/ 下已有文章提炼，覆盖项目介绍、技术复盘、架构讨论、性能优化、架构设计等类型。

---

核心原则

用工程师的精确度写，直接说事，不绕弯子，但要让没接触过这个领域的读者也能读下去。

每篇文章都要有一个可以一句话说清的核心论点。写之前先问自己——这篇文章想让读者记住什么？如果说不清楚，先别动笔。

工程准确和通俗易懂不矛盾。准确指的是机制不能写错、判断要有依据，不是把术语和代码堆满。读者的下限按「听过这个方向、但没碰过具体实现」来设定——术语第一次出现要带一句白话讲明白是什么，代码块能少则少。宁可多用一句白话解释，也不要让读者卡在某个词上往回翻。

与 Anthropic/Codex 博客的关系： Peri 博客借鉴了 Codex 官方博客的教学式渐进结构（先讲概念定义，再讲为什么重要，最后讲怎么做）、关键术语 bold 强调、以及丰富的交叉引用习惯。但有三个刻意的差异——(1) Peri 的段落更短（2-4 句 vs 3-5 句），保持工程师的切分感；(2) Peri 的语气更直接，可以下判断、可以表现偏好，不完全追求 Codex 的临床式冷静距离感；(3) Peri 不回避第一人称（我们、我），用个人经历和具体场景驱动叙述。

---

写作流程

按以下六步推进，前五步每步获得用户确认后再进入下一步，第 5 步写完后接第 6 步独立审查。

第 1 步：用户提出方向，AI 用 grill 质询对齐核心命题。 用户描述想写什么——一个功能的设计理念、一个踩坑复盘、一次性能调优经历。AI 在这个阶段只问澄清性问题，不提方案。

grill 必须显式覆盖「重心维度」。同一题材往往有多个可行的重心，比如讲工具设计可以从「工具机制」切入，可以从「能力关系」切入，可以从「用户姿势」切入。让用户在 grill 阶段选重心方向，比让重心被默认成某一个、用户在初稿里发现偏移要省事得多。

grill 结束的标志是用户确认了「核心命题一句话」——这篇文章想让读者记住的那一句话。这一句话确认后再进入第 2 步出标题。标题是包装，命题是内容，确认包装之前先确认内容。

第 2 步：AI 出 N 个大标题。 AI 根据方向提 5 个大标题供选择。大标题说清楚文章对象和核心价值，不写驳论句式（「不是 X，是 Y」），不漂移到其他功能。格式参照「大标题规则」。

第 3 步：用户选大标题。 用户从 5 个中选一个，或者提出修改方向让 AI 再出 5 个。可以反复直到满意。

第 4 步：AI 出大纲，用户审阅。 AI 给出章节标题列表（小标题），每个标题只说这节讲什么行为/机制。用户审核——砍掉偏离论点的章节、调整顺序、合并冗余。大纲确认后才进入写作。

第 5 步：AI 写出全文。 严格按确认的大纲写。

动笔前必须先过写前 7 条红灯（30 秒自检，写完再查就晚了）：

1. 中文冒号「：」——这篇正文一句都不能有。项目地址行的冒号是唯一例外。
2. 任何引号（「」和 ""）——一个都不能有。术语和观点不加引号直接写。
3. 每个 h2 的第一段——必须至少两句话。一句话的段落立即跟下一段合并。
4. 每个小标题——扫一遍有没有逗号串联两件事、有没有"适合/刚好/才是对的"等判词、有没有"怎么/如何/为什么"设问、有没有 CamelCase 代码标识符（SearchExtraTools→搜索工具、ToolResult→工具执行结果）。
5. 全文搜 为什么 怎么 如何 本文 这篇文章——小标题里出现的一律改成陈述句，正文里「本文展开」「这篇文章记录」一律删除。
6. 结尾最后一段——必须回应开头场景，禁止复读正文已讲过的机制结构。
7. 全文搜 ""——和「」一样禁止，一个不留。

这 7 条检查的是生成时最高频的机械性违规——标点习惯、段落结构、标题措辞和结尾套路——写完再让 subagent 抓出来修，不如写之前扫一眼直接避坑。

写完后不直接交付用户，进入第 6 步。

第 6 步：subagent 文风审查（不可跳过）。 写完全文后，派一个独立 subagent（general-purpose，全新上下文）做一轮文风审查。把本 skill 完整路径和文章路径交给 subagent，要求它按 skill 全文逐项核对，重点查这些高频违规项：

• 故事性叙事——拟人化模型行为（模型「撒谎」「老老实实」）、戏剧口语替代后果（「翻车」「废了」）、叙事过渡引子（「先说结论」「下面分别讲」「回头看」）
• 单句成段（一句话前后空行）
• 设问自答（「为什么不 X？因为 Y」）
• 代码块数量（整篇 1-2 个，只许报错信息和极简示意）
• 实现术语通俗化（内部函数名、类型标识符、框架 API 是否已替换为通用 CS 概念）
• 术语首次出现是否带白话解释
• 禁用词与禁用标点（中文冒号、双引号、「说白了」「本质上」等）
• 小标题是否机制描述、有无态度性措辞或破折号