原型 · 预览版:收录官方注册中心里的全部服务器,每 30 分钟同步一次。使用 Google 登录即可撰写评价。原型 · 每 30 分钟更新
PopNx MCP为使用 AI 的人准备的 MCP 服务器 · 用大白话讲清楚

technical-writing Skill

代码仓库 ↗

作者:luoling8192★ 2191 个 skill

安装

What it does

中文内部技术写作的 agent skill,约束设计文档 / 评审稿 / postmortem / 分享稿场景的语气、句法、结构

  • Connects Instruction files the AI reads
  • Account or key Not confirmed yet (README not read yet)
  • Category 写代码
给作者:在 README 中加徽章

如果你是作者,可把这段代码贴到 README。徽章会链接回本页。

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/skill/luoling8192-technical-writing.svg)](https://mcp.popnx.com/en/skills/luoling8192-technical-writing)

可搭配使用

在同一工作中把 AI 连到服务的 MCP

REA

Reverse engineer anything from your terminal or agent with one CLI and MCP server.

作者:morluto广泛使用↓ 38.9万/周★ 46.4万5天前更新

MCP · 连接服务在你的电脑上运行

Fallow

Codebase intelligence for TypeScript and JavaScript, exposed as structured MCP analysis tools.

作者:fallow-rs广泛使用↓ 244.1万/周★ 5374今天更新

MCP · 连接服务在你的电脑上运行

Desktop Commander

MCP server for terminal commands, file operations, and process management

作者:wonderwhy-er广泛使用↓ 74万/周★ 1万5天前更新

MCP · 连接服务在你的电脑上运行

相似的 Skill

同类工作,排序与 Skill 列表相同

与相似项目对比
本项
technical-writing
reaandrej-karpathy-skillsgraphifyMoneyPrinterTurbo
作者luoling8192morlutomultica-aiGraphify-Labsharry0703
Skill 数11111
GitHub 星标219465,460233,910149,364144,149
最近代码更新2026年5月27日2026年11月17日2026年4月20日2026年11月17日2026年11月17日
许可证MITMIT–Apache-2.0MIT

luoling8192 提供的 1 个 Skill(指令集),AI 读取后照做 · 不是 MCP server

Skill 和 MCP 有什么不同

MCP = 手

把 AI 连到外部服务或数据,例如读取 Notion 或开发票。需要有程序或服务器在运行。

Skill = 手册

教 AI 怎么做某项工作的文本文件,不连接任何服务。

有些会重叠:少数 Skill 带有调用工具的脚本,少数 MCP 只提供知识。请从你想完成的工作出发。

适用的应用

Claude CodeCodexCursorGitHub CopilotWindsurf

依据开发者 README 和 repo 中的文件夹

安装

Is it safe?

  • Who made it

    GitHub account luoling8192 (person), 8 years old

  • Use and upkeep

    ★ 219 stars, few users so far · code last changed 2026年5月27日

  • Any scripts?

    No, plain text files the AI reads and follows

  • Uses the internet?

    No scripts, so it does not go online by itself

  • Changes machine-wide settings?

    No hooks or writes to machine settings found

Checked automatically from the repo files at commit 5f684e9 (read only, nothing was run). Not a safety guarantee: read it and decide for yourself

第一步:你用哪个 AI?

选择你用的应用,本页只显示该应用的安装方法

Option 1Upload to claude.ai (web and app)

Uploading to claude.ai would fail: the description is over 200 characters (264). Use "Let the AI install it" instead

Option 1让 Claude Code 帮你安装

复制这句话,粘贴到 Claude Code 的对话中

Where to install

正在检查命令 · 通过后才会显示复制按钮

正在检查命令 · 通过后才会显示复制按钮

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

重新打开 Claude Code,输入 /technical-writing,或直接提出相关任务,Claude 会自动选用

Checked against official docs 2026年11月12日 · Source: code.claude.com

For Terminal users

Skill 是 AI 会照做的指令。安装前先阅读文件,只安装可信开发者的 Skill。

开发者推荐的方式

安装 Node.js(如果还没有)

已经装好了吗?先检查 · 打开终端,输入这条命令后按 Enter

node -v
  • 显示版本号(例如 v26.13.1)= 已安装,可跳过这一步
  • 显示 "command not found"(Windows 显示 "is not recognized")= 还没安装,或刚装好但需要关掉终端再重新打开
怎么打开终端

Mac:按 ⌘ + Space,输入 Terminal 后按 Enter

Windows:打开“开始”菜单,输入 Windows PowerShell,然后选“打开”

还没安装: 打开官方下载页,选择 LTS 版本和点选式安装程序:Mac 用 .pkg · Windows 用 .msi。双击后一路下一步即可,不需要 curl 命令

打开 Node.js 下载页 ↗

装好后关掉终端再打开,重新运行同一条命令,应显示版本号: node -v

安装一次,所有需要 Node.js 的工具都能用

正在检查命令 · 通过后才会显示复制按钮

摘自开发者 README,会下载并运行开发者的代码

  1. 打开终端

    Mac:按 Command+空格输入 Terminal · Windows:下方命令在 PowerShell 中无法使用,请改用上方的“让 AI 帮你安装”

  2. 把 skill 文件夹复制到 ~/.claude/skills

    这条命令把 repo 下载到临时文件夹,只复制含 SKILL.md 的文件夹

    正在检查命令 · 通过后才会显示复制按钮

  3. 重新打开 Claude Code,输入 /technical-writing,或直接提出相关任务,Claude 会自动选用

自己安装的 Skill 可用于 ChatGPT 桌面应用、Codex CLI 和 IDE 中的 Codex 扩展 · 网页版和手机版 ChatGPT 不能使用自己安装的 Skill,只能使用目录中插件自带的 Skill

ChatGPT 桌面应用

ChatGPT 桌面应用内置 Codex,Codex 从 ~/.agents/skills 文件夹读取 Skill

Option 1让 ChatGPT 帮你安装

在 ChatGPT 桌面应用中打开 Codex,把这句话粘贴到对话中

Where to install

正在检查命令 · 通过后才会显示复制按钮

正在检查命令 · 通过后才会显示复制按钮

The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Option 2自己放入文件夹

把 technical-writing 文件夹放到 ~/.agents/skills/technical-writing

~ 是你的主文件夹($HOME)

For Terminal users

Skill 是 AI 会照做的指令。安装前先阅读文件,只安装可信开发者的 Skill。

  1. 打开终端

    Mac:按 Command+空格输入 Terminal · Windows:下方命令在 PowerShell 中无法使用,请改用上方的“让 AI 帮你安装”

  2. 把 skill 文件夹复制到 ~/.agents/skills

    这条命令把 repo 下载到临时文件夹,只复制含 SKILL.md 的文件夹

    正在检查命令 · 通过后才会显示复制按钮

安装之后

  • ChatGPT 桌面应用:打开侧边栏中的 Skills,确认 Skill 已出现
  • 使用方法:在 ChatGPT 中输入 @ 并选择 Skill · 在 Codex CLI 或 IDE 扩展中运行 /skills,或输入 $ 加 Skill 名称
  • Codex 会自动发现新安装的 Skill;如果没有出现,请重启 Codex

Checked against official docs 2026年11月15日 · Source: learn.chatgpt.com

网页版和手机版 ChatGPT

不能使用你自己安装的 Skill,只能使用目录中插件自带的 Skill

想在 ChatGPT 中使用这个 Skill,请按上面的方法使用 ChatGPT 桌面应用

Checked against official docs 2026年11月15日 · Source: learn.chatgpt.com

Option 1让 Codex 帮你安装

复制这句话,粘贴到 Codex 的对话中 · 适用于 ChatGPT 桌面应用中的 Codex、Codex CLI 和 IDE 扩展

Where to install

正在检查命令 · 通过后才会显示复制按钮

正在检查命令 · 通过后才会显示复制按钮

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Codex 会自动发现新安装的 Skill;如果没有出现,请重启 Codex · 使用方法:在 ChatGPT 中输入 @ 并选择 Skill · 在 Codex CLI 或 IDE 扩展中运行 /skills,或输入 $ 加 Skill 名称

Checked against official docs 2026年11月15日 · Source: learn.chatgpt.com

For Terminal users

Skill 是 AI 会照做的指令。安装前先阅读文件,只安装可信开发者的 Skill。

  1. 打开终端

    Mac:按 Command+空格输入 Terminal · Windows:下方命令在 PowerShell 中无法使用,请改用上方的“让 AI 帮你安装”

  2. 把 skill 文件夹复制到 ~/.agents/skills

    这条命令把 repo 下载到临时文件夹,只复制含 SKILL.md 的文件夹

    正在检查命令 · 通过后才会显示复制按钮

  3. 重新打开 Codex 并提出相关任务,Codex 会列出这个 skill

Option 1让 Cursor 帮你安装

复制这句话,粘贴到 Cursor 的对话中

Where to install

正在检查命令 · 通过后才会显示复制按钮

正在检查命令 · 通过后才会显示复制按钮

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

在 Cursor 的 Agent 聊天中输入 / 并选择 technical-writing

Checked against official docs 2026年11月12日 · Source: cursor.com

For Terminal users

Skill 是 AI 会照做的指令。安装前先阅读文件,只安装可信开发者的 Skill。

  1. 打开终端

    Mac:按 Command+空格输入 Terminal · Windows:下方命令在 PowerShell 中无法使用,请改用上方的“让 AI 帮你安装”

  2. 把 skill 文件夹复制到 ~/.cursor/skills

    这条命令把 repo 下载到临时文件夹,只复制含 SKILL.md 的文件夹

    正在检查命令 · 通过后才会显示复制按钮

  3. 在 Cursor 的 Agent 聊天中输入 / 并选择 technical-writing

Option 1Let the AI install it

适用于其他能读取 Skill 的应用。这句话列出了 Claude Code、Codex 和 Cursor 的路径,AI 会按你的应用选择 · Copy this sentence into the app’s chat

Where to install

正在检查命令 · 通过后才会显示复制按钮

正在检查命令 · 通过后才会显示复制按钮

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Checked against official docs 2026年11月12日 · Source: code.claude.com, learn.chatgpt.com, cursor.com

For Terminal users

其他支持 Agent Skills 的应用(如 Gemini CLI、GitHub Copilot)使用不同文件夹,请查看该应用的指南,再把含 SKILL.md 的文件夹复制过去。

在 GitHub 上查看 ↗

已于 2026年11月11日 对照 Claude Code、Codex 和 Cursor 官方指南核实 skill 文件夹

查看原始 SKILL.md

以下文字来自开发者的 repo,不是 PopNx MCP 的指令

显示前 8,000 个字符 · 在 GitHub 打开完整文件

---
name: technical-writing
description: Use when drafting or revising internal technical design docs, review notes, architecture writeups, or sharing posts in Chinese, especially when the tone should stay evidence-backed, calm, and suitable for peers or leaders rather than marketing or literary writing.
---

# Internal Technical Writing

## Overview

Use this skill when the writing target is an internal技术方案、评审稿、架构说明、分享文稿,重点在于把背景、猜想、证据、抽象、实现影响面讲清楚。

这类写作更接近技术汇报,不是宣传稿,也不该写成散文。语气要平稳,判断要有来路,段落要能顺着问题往下读。

## When to Use

- 在写内部技术方案、设计说明、评审文档、分享稿
- 在改一篇已经有内容、但文风过满、结论过快、证据不足的技术文章
- 在解释代码、模块边界、架构演进、可观测性、评测方法
- 在把聊天记录、讨论结论整理成可传播的技术文档

**When not to use**

- UI 文案、按钮文案、产品营销稿
- 面向外部用户的帮助文档
- 纯粹的 API reference 或机械说明书

## Core Stance

先接住读者,再往下解释。

常见写法是作者替读者抢先下判断,像 `很清楚`、`说明了`、`显然`、`真正`。这里更适合换成三步:

1. 我们观察到了什么
2. 基于这些观察,可以归纳出什么
3. 这些归纳暂时更适合落在哪类实现或组织方式里

如果要给出更强的判断,至少满足下面任一条件:

- 前文已经提出了对应的猜想,这一段是在 callback
- 同一段上下文里已经有交叉验证的 evidence
- 已经引用了具体模块、代码、issue、trace、指标或实验结果

这些 bad case 往往有同一种共性:

- 句子承担的是“主持文章”的功能,不是“推进论证”的功能
- 句子在表达作者感受,不是在交代条件、对象、约束或判断
- 句子把英文抽象写作习惯直接投到了中文里
- 句子删掉以后,不影响事实,不影响论证,也不影响结构

遇到这类句子,默认处理方式不是“换个更文雅的说法”,而是:

1. 先判断这句是否真的提供信息
2. 如果不提供信息,直接删除
3. 如果提供信息,就把信息改写成条件、对象、关系、结果

## Preferred Structure

写长文时,优先用这条主线:

`背景 -> 拆解现状 -> 提出猜想 -> 分节解答 -> 回指前文 -> 影响面 -> 可观测性 / eval -> 收束`

如果文章围绕一个系统展开,可以把每一节都写成“在回答前面哪个问题”。这样读者会知道当前段落在解决什么,而不是只看到一串观点。

更具体一点,常见结构会是:

- 先交代背景和目标
- 拆现状,尤其是已有系统的优势、局限、宏观规律
- 把猜想或设计问题提出来
- 逐节解释每一层能力怎样补上
- 回到代码、模块、数据流、观测面和评测面

如果某一节表面上在讲模块,实际目的是在替另一个概念安家,可以优先用这种结构:

1. 先用一个很短的 quote 收住上下文
2. quote 里优先放 `mindmap` 或极简结构图
3. 再给一个生命周期或时序图
4. 最后才进入正文,解释这个概念为什么放在这里、怎样和现有模块对上

如果要给 leader 或评审一个放在最开头的 TL;DR,优先用三段结构:

1. 先讲启发来源或背景变化
2. 再讲当前系统已经具备哪些输入、还缺哪一层结构
3. 最后讲新模块设计和架构决策

这个 TL;DR 只保留三类信息:

- 原因
- 猜想
- 决策

不要在 TL;DR 里复述整篇目录,也不要解释作者接下来会怎么写。

## Language Rules

中文语气以自然、平实、技术同伴之间的说明为主。

- 中文引用统一用 `「」`
- 少用修辞和比喻,尤其是面对前线开发和内部评审
- 少用居高临下的口吻,避免说教感
- 少写成议论文式对抗句,优先顺着读者的理解路径展开
- 专有概念按正式名字书写,大小写保持稳定,例如项目里的 `Collector`、`Scheduler`、`Alert` 这类专名,全文统一一种写法
- 指标、能力、链路这些名词先钉住,再配动词和形容词;优先复用已经确定的词系,例如 `流通性`、`筛选`、`聚合`、`命中`,不要临时拼接近义词
- 不要写口语化的过场句,例如 `聊到这里`、`继续往下看`、`这条方向很值得继续推开`、`先把这件事单独拿出来说`、`最后可以用一句话收住`;如果一句话只是在主持文章,不承载信息,就直接删掉
- 少用空评价词,例如 `很现实`、`很重`、`很轻`、`很顺`;改成具体约束、具体风险、具体影响

下面这类句型要主动收一层:

- `不是……而是……`
- `不在……而在……`
- `为什么?原因其实很直接`
- `这条路径已经很清楚了`
- `说明了一件事`
- `自然会`
- `真正`

更稳妥的写法通常是:

- `也许你会先想到……`
- `把视线收回到今天的代码里,会先看到几组比较稳定的规律`
- `顺着这些模块往回看,可以归纳出……`
- `前面提到的猜想,在这里开始有了一个更具体的回答`
- `先把判断放轻一些,后面再结合代码或指标继续说明`

遇到段落里的关键问题句,可以适度用 `**...**` 强调,但只留给真正的主问题,不要把普通判断句全部加粗。

## Buzzword Blocklist

下面这些词在中文技术文档里几乎都是「让句子看起来有信息,但读完不知道发生了什么」。看到先停一下,能换成具体动作 / 对象 / 约束就换掉。

原则:不是逐词替换,而是逐句重写。原句里如果只有黑话词承载信息,整句通常没信息。删掉看论证少不少东西,少了再补具体的,没少就让它消失。

### 抽象抢戏词

- `生态` / `生态位` / `产品生态` → 列出具体依赖关系、用户类型或集成方
- `赋能` / `赋能用户` → `让用户能 X` / `把 X 能力开放给 Y`
- `闭环` / `形成闭环` → `X 之后 Y 也接进去了` / `现在能从 A 走到 B 再回到 A`
- `抓手` / `核心抓手` → `我们能改的那一个变量是 X`
- `心智` / `用户心智` / `心智模型` → `用户在第一次看到 X 时会怎么想 / 怎么操作`
- `链路打通` / `打通` → `A 现在能调用 B` / `A 写入的数据 B 也能读到`
- `沉淀` / `沉淀经验` / `沉淀方法论` → `记录到 docs/X` / `整理成 skill / runbook`
- `落地` / `落地能力` / `落地场景` → `在 A 模块实现` / `在 B 业务用上`
- `心力` / `认知负担` → `需要记住 X 个步骤` / `上手要先理解 Y`
- `收口` / `统一收口` → `所有 X 都走 Y 一个入口`
- `加持` / `AI 加持` → `加了 X 之后能 Y` / `在 X 步用了 LLM`
- `底座` / `底层逻辑` → `基础设施层是 X` / `这件事成立的前提是 Y`

### 评价腔 / 主持腔

- `很值得` / `非常值得` → 给具体理由:值得在哪个维度上
- `极致` / `极致体验` → 改成具体指标:延迟降到多少、步骤减到几步
- `丝滑` / `顺畅` → 改成具体约束:哪步原本卡,现在跳过了
- `深度集成` / `深度对接` → 改成集成点的具体范围
- `一站式` → `在 A 入口能完成 B / C / D`
- `颠覆` / `重塑` → 默认不用;真要用得有 before / after 对比

## Evidence-First Writing

写代码和架构时,避免直接把实现细节翻译成抽象结论。

推荐顺序:

`代码 / issue / trace / metric -> 宏观规律 -> 抽象归纳 -> 设计判断`

例如,不要直接写:

> 当前代码里,这条路径已经很清楚了。

更适合写成:

> 把视线收回到今天的代码里,会看到几组比较稳定的宏观规律。顺着这些模块往回看,可以先归纳出一个较稳定的结构。前面提到的几层能力,也因此开始有了几种更适合继续承接的实现位置。

## Reader-Aware Explanations

很多技术分歧来自“作者默认读者已经接受了自己的前提”。这里更适合先猜测读者可能会怎么想,再把误会拆开。

常用句法:

- `也许你会先想到定时巡检,像是……`
- `顺着这个方向想下去,会发现我们更关心的是……`
- `这样理解,会更贴近这次设计的边界`

适合接一个 quote:

> 一条巡检任务如何按预定周期扫描每个指标

然后再转入你真正要讨论的问题:

> 持续涌入的原始日志,怎样在不拖慢写入链路的情况下,被判定成一条值得通知的告警

## Few-Shot Fixes

下面这些例子比抽象规则更重要。写作时如果遇到类似句式,优先按这个方式改。

### 1. 不要把英文里的 `real / realize / reality` 直接翻进中文

原句:

> 一旦把告警规则接到多个采集端上,粒度问题会马上变得很现实。

问题:

- `现实` 在这里不是合适的表语
- 主语是 `粒度问题`,谓语是 `变得`,搭配不成立
- 句子像是在表达感受,不是在说明约束

改写:

> 可以预见的是,告警规则接入多个采集端之后,规则粒度的控制会很重要。

为什么这样改:

- 先写条件:`接入多个采集端之后`
- 再写对象:`规则粒度的控制`
- 最后写判断:`会很重要`

### 2. 不要用空评价词替代约束

原句:

> 这样的组合很顺。

问题:

- `很顺` 只有情绪,没有信息
- 读者不知道顺在成本、链路、延迟还是模块边界

改写:

> 这种组合更接近实际分工。

或者:

> 这种组合能把日志写入链路和告警判定链路拆开。

为什么这样改:

- 直接说分工关系
- 或者直接说结构变化
- 不用作者主观感受替代技术判断

### 3. 不要用对立句法硬造强调

原句:

> 它值得认真看的地方,不在宣传语,而在它把一组采集与告警机制组织得很完整。

问题:

- `不在……而在……` 容易写出说教感
- 读者还没进入正文,就先被作者带去站队

改写:

> 更值得认真拆开的,是它把一组采集与告警机制组织得比较完整。

为什么这样改:

- 少掉对立结构
- 句子仍然保留重音
- 读者更容易直接进入后文

### 4. 不要用过场句替代内容

原句:

> 聊到这里,告警去重相关的模型也该放进来一起看了。

问题:

- 这是主持人口吻,不是技术文档
- 删掉这句,论证不会损失任何信息

改写:

> 告警去重相关的模型也需要放进来一起讨论。

为什么这样改:

- 直接进入主题
- 不拿过场句占正文位置

同类句子也直接删掉,不做“温和改写”:

原句:

> 先把「压缩」这件事单独拿出来说。

问题:

- 这是主持句,不提供任何新信息
- 删掉之后,后文论证不受影响

处理:

> 直接删除,让下一句作为段落开头

### 5. 不要把“主持文章”的句子写进正文

原句:

> 这张图想说明的事情很简单。

问题:

- 这是主持句,不提供图外的新信息
- 读者真正需要的是图后的结论,不是作者先出面做导语

处理:

> 直接删除,下一句直接解释图里的结构关系

原句:

> 接下来进入这一节真正关心的问题:

问题:

- 这句话只是在带节奏,没有补充任何事实
- 如果下一句本身已经是问题句,这一句就没有存在价值

处理:

> 直接删除,或者把下一句改成完整的问题句

原句:

> 最后可以用一句更轻一点的话结束:

问题:

- 这句话只是在管理作者自己的写作动作
- 正文里不需要暴露作者“现在准备收尾”

处理:

> 直接删除,让引文或结论直接出现

### 6. 论证有顺序,就直接写成 1. 2. 3. 4.

原句:

> 第一,采集端很多,但日志最终还是会被收束到告警引擎。
> 第二,采集层已经承担了日志归一化……
> 第三,告警引擎自己已经天然拥有一组规则边界……
> 第四,外围模块已经把不少有价值的事件散落出来了……

问题:

- 如果只是散写四段,读者不容易看出这是一组并列论据
- 论据顺序和论证强度不够醒目

改写:

1. 采集端很多,但日志最终还是会被收束到告警引擎。
2. 采集层已经承担了日志归一化、字段提取、标签注入、来源标注。
3. 告警引擎自己已经拥有一组稳定的规则边界。
4. 外围模块已经给出了足够多的事件与状态。

为什么这样改:

- 论证顺序被显式标出来
- 每一点都能单独成立
- 后文更容易 callback

### 7. 指标名和动作词要属于同一套语义系统

原句:

> 第一组命题靠近转化率。不同 source 类型进入系统之后,有多少被 dedupe 掉,有多少在 cooldown 里停住,有多少被 policy 接住,最后又有多少真的升级成一条告警。

问题:

- `转化率`、`dedupe 掉`、`停住`、`接住`、`升级` 混了多套词
- 指标名和动作词不在一个语义系统里

改写:

> 1. 计算流通性。
>    不同 source 类型进入系统之后:
>    - 有多少被 dedupe 筛选
>    - 有多少进入 cooldown 聚合
>    - 有多少被 policy 命中
>    - 最后又有多少升级成一条告警

为什么这样改:

- 先钉住指标名:`流通性`
- 再统一动作词:`筛选 / 聚合 / 命中 / 升级`
- 这一组词能互相支撑,不会彼此打架

### 8. 表面在讲模块,实际是在给概念安家时,先给短图

原句:

> 从采集入口到告警判定层……
> 后面直接开始解释告警引擎、采集层、规则模块……

问题:

- 读者还不知道这节到底想回答什么
- 容易把“解释模块”写成“复习已有系统”

改写结构:

1. 先点明问题:`这一节表面上在讲告警引擎,真正要回答的是去重模块应该放在哪里。`
2. 用一个很短的 `mindmap` 收住周边模块
3. 再给一个生命周期图
4. 最后才写 `1. 2. 3. 4.` 论据,把概念安到现有系统上

为什么这样改:

- 图负责建立工作机理
- 正文负责回答设计问题
- 模块介绍不会挤掉概念论证

### 9. TL;DR 先讲启发来源,再讲问题定义,最后讲模块设计

原句结构:

> 当前系统已经具备了大量可利用的信息来源……
> 我们的猜想是……
> 基于这个判断,我们的决策是……

问题:

- 起手就落在“系统现状”,重心太平
- 启发来源没有先出现,读者不容易立刻进入问题
- `基于这个判断,我们的决策是` 也带一点主持口吻

更合适的结构:

> 第一段:先讲外部启发或上游项目带来的变化
> 第二段:再讲日志、指标、trace、事件等输入已经存在,系统接下来要整理的是反复出现、需要聚合的重复告警
> 第三段:直接提出新模块设计,以及消息队列、异步消费框架这类架构决策

例子:

> 上游某个监控项目让大家看到了另一种告警形态……
> 当前系统也已经具备了足够多的输入和状态来源……
> 这里提出一个新的模块设计……

为什么这样改:

- 第一段先建立背景和动机
- 第二段再定义问题
- 第三段直接落到决策
- 读者扫三段就能抓住全文主轴

### 10. 不要把作者感受写成技术判断

原句:

> 这样的组合很顺。

原句:

> 这条路径很清楚。

原句:

> 这会马上变得很现实。

问题:

- `顺`、`清楚`、`现实` 都是作者感受,不是技术判断
- 读者不知道到底顺在什么、清楚在哪里、约束是什么

改写方向:

> 先写条件
> 再写对象
> 最后写判断

例如:

> 可以预见的是,告警规则接入多个采集端之后,规则粒度的控制会很重要。

### 11. 不要把结构写成隐喻动作

原句:

> 散落出来了

原句:

> 收拢出来

原句:

> 往一层里收

原句:

> 延展下去

原句:

> 停在 action skipped

原句:

> 落在 failed

问题:

- 这些词在脑子里成立,是因为作者把系统想成了“流动中的东西”
- 一旦写成中文,主谓和宾语关系经常不成立
- 它们会把“状态”“结构”“结果”误写成“位置”或者“动作”

改写方向:

- `提供了`
- `整理出来`
- `集中到同一层处理`
- `继续追加后续处理`
- `最终生成了 action skipped`
- `最终生成了 failed`

## Lists, Quotes, and Flow

不要为了“像文章”而硬把所有东西写成整段 prose。内容本来就是 list-shaped 时,直接列出来更清楚。

适合列出来的内容:

- 设计目标
- 猜想
- 模块影响面
- 待补充实现点
- 评测命题
- 适用 / 不适用场景

如果一组判断本身带有论证顺序,优先直接写成 `1. 2. 3. 4.`,不要把它们散落成几段并列 prose。

适合用 quote 的内容:

- 想强调的命题
- 读者可能先想到的另一种问题定义
- 控制论 / 系统论 / issue 摘录中的关键句

适合用箭头的内容:

- `event -> dedupe -> alert`
- `background -> hypothesis -> answer`
- `collect -> match -> notify`

## Module-Level Writing

只谈抽象很容易飘。只谈代码又会失去设计视角。内部技术文档通常需要两层一起出现:

- 抽象层:概念、边界、语义、主张
- 实现层:模块、类型、采集器、规则、存储、trace、eval

写实现层时,尽量把模块面摊开:

- 哪些模块已经存在
- 哪些模块只体现出局部规律
- 哪些模块更适合作为后续替代实现
- 哪些地方需要补偿、迁移、压缩、解耦

如果一段在说“改造”或“补充实现”,优先给出可扫描的块,例如:

> 可能涉及到的补充实现:
> - 告警存储层 CRUD 拓展
> - 告警编排从 inline 转向异步消费
> - tracing 压缩与聚合策略
> - 可观测面板的链路展示与命题聚合

## Ton

讨论

提问、分享技巧或报告无法使用。按“有帮助”数量排序。

还没有帖子,欢迎第一个提问或分享。

此处内容由用户撰写,不代表 PopNx 团队。

登录后发帖

来自 GitHub

GitHub 星标
219
开发者
luoling8192
许可证
MIT
最近代码更新
2026年5月27日
repo 中的 SKILL.md 文件(含译本和模板)
1
主题
agent-skill, chinese, claude-code, codex, documentation, technical-writing