프로토타입 · 미리 보기: 공식 레지스트리의 모든 서버를 담고 있으며 30분마다 동기화해요. Google로 로그인하면 리뷰를 쓸 수 있어요.프로토타입 · 30분마다 업데이트
PopNx MCPAI를 쓰는 사람을 위한 MCP 서버 · 쉬운 말로 설명해요

technical-writing Skill

저장소 ↗

제작자: luoling8192★ 219skill 1개

설치

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만/주★ 5.4천오늘 업데이트

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 별219463,670233,682148,887143,987
마지막 코드 변경2026년 5월 27일2026년 11월 17일2026년 4월 20일2026년 11월 17일2026년 11월 16일
라이선스MITMIT–Apache-2.0MIT

luoling8192의 Skill(지시 묶음) 1개, 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 1Claude 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가 따르는 지시예요. 설치 전에 파일을 읽고, 믿을 수 있는 제작자 것만 설치하세요.

제작자가 권하는 방법

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 1ChatGPT에게 설치 맡기기

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가 따르는 지시예요. 설치 전에 파일을 읽고, 믿을 수 있는 제작자 것만 설치하세요.

  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만 쓸 수 있습니다

이 Skill을 ChatGPT에서 쓰려면 위 방법대로 ChatGPT 데스크톱 앱을 쓰세요

Checked against official docs 2026년 11월 15일 · Source: learn.chatgpt.com

Option 1Codex에게 설치 맡기기

이 문장을 복사해 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가 따르는 지시예요. 설치 전에 파일을 읽고, 믿을 수 있는 제작자 것만 설치하세요.

  1. 터미널 열기

    Mac: Command+스페이스 후 Terminal 입력 · Windows: 아래 명령은 PowerShell에서 안 돼요. 위의 “AI에게 설치 맡기기”를 쓰세요

  2. skill 폴더를 ~/.agents/skills에 복사

    repo를 임시 폴더에 내려받고 SKILL.md가 있는 폴더만 복사해요

    명령을 확인하는 중 · 확인을 통과하면 복사 버튼이 나타나요

  3. Codex를 다시 열고 관련 작업을 요청하면 Codex가 skill을 목록에 보여 줘요

Option 1Cursor에게 설치 맡기기

이 문장을 복사해 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가 따르는 지시예요. 설치 전에 파일을 읽고, 믿을 수 있는 제작자 것만 설치하세요.

  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

Gemini CLI, GitHub Copilot 같은 다른 Agent Skills 지원 앱은 폴더가 달라요. 그 앱 안내를 보고 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