agentsclimarketplace

Writing architecture docs

Skill wanghong5233/agent-engineering-kit/cursor/.cursor/skills/writing-architecture-docs

A reusable, production-grade .cursor/ engineering package for Cursor / Claude Code / Agent IDEs. Rules, skills, commands, and deterministic safety hooks extracted from a real Agent project.

Install
npx -y skills add wanghong5233/agent-engineering-kit --skill writing-architecture-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Write or refactor architecture/design/ADR docs (current-state + first-principles form). Use when editing `docs/*设计*`/`*架构*`/`*ADR*`/`*RFC*`, or user asks write/修改 architecture/设计/ADR docs, or complains doc is 啰嗦/口水/AI味/AI痕迹/对话记录/辩证过程. Do NOT use for README or pitfall.

SKILL.md

4.0 KB, as published. Nobody here has run it

Writing Architecture Docs

一句话准则

架构文档只回答两个问题：当前实现是什么 与 为什么是这个形态。其他都属污染。

硬性禁止（命中即删）

反模式判断特征归宿
结论先行 / TL;DR / 摘要用 **xxx** 开头总结全文删，每节都是结论无需元结构
辩证过程 / 四轮反应 / 讨论记录"第一反应→反驳→第二反应"序列agent-transcripts/
外部证据 / 产品对比 / 调研表列举 ChatGPT / Claude / Letta 等做法删，至多一句泛指
已删除/不再维护工件清单列出被移除的文件、env、字段git log / CHANGELOG
运维现象"启动失败 / wheel 冲突 / ABI 问题 / Windows-WSL 下 xxx"issue tracker / pitfall
过程时态"之前草案……落地阶段……这次决定……"改现在时
对话/汇报语气"这里我思考 / 可见 / 迫使我们 / 就 / 说白了 / 其实"直接删
散文堆叠连续 3 段超 5 行改表格 / mermaid / 签名代码块

必要章节

每节缺哪一块不强求，出现即必须是这种形态（完整示例见 references/examples.md）：

1. 现状陈述（一句 + 一图）

现在时陈述"当前实现是什么"，配 mermaid 或分层职责表。

2. 分层职责表

三列 层 / 负责 / 不负责，一层一行，无解释段落。

3. 第一性原理分析（为什么是这个形态）

维度表，不用散文。维度名从以下挑选：

  • 数据规模（量化：行数、QPS、体积）
  • 能力归属（哪个角色负责这件事）
  • 写入/读取成本（延迟、token、依赖体积）
  • 故障域（失败面、传染性）
  • 可逆性（未来换方案的迁移成本）

三列 维度 / 分析 / 结论，无散文。

4. 接口契约（签名 + 不变式）

接口签名用 text 块；不变式编号列出。失败时必须失败，不返回伪成功。

5. 可逆性 / 重评触发条件（如适用）

"当前选 A，未来可能换 B"类决策必须给量化门槛：

触发判断以运行时指标为准，不在无数据时提前决策。

写作微观规范

  • 中文正文 + 英文代码/标识符
  • 现在时陈述：❌"我们决定采用 X" → ✅"采用 X"
  • 禁用口语连接词：就 / 其实 / 说白了 / 可见 / 显然
  • 无感叹号、无 emoji
  • 禁止 AI 模板句："这不是 X，而是 Y" / "值得注意的是" / "从某种意义上" / "显著提升"
  • 标题写对象或契约，不写口号：✅运行时状态机，❌为什么这是正确架构
  • 第一性原理 必须落成维度表；否则改名为 设计约束
  • 表格 > 列表 > 段落；段落不超过 3 行
  • 章节引用用 §X.Y 或 [附录 B](#...)，不写"上文提到过"

自检（提交前必过）

对每一行自问：

  • 描述的是"当前架构"还是"过程/对话/运维"？后者→删
  • 能用表格/图/签名代替吗？能就替
  • 删掉这行读者会漏什么架构事实？漏不掉→删
  • "为什么"是否走了第一性原理维度表？口水论证→改表
  • 标题是否像工程索引，而不是 AI 摘要标题？不是→改
  • 是否有无证据形容词（"稳定 / 高效 / 优雅"）？→ 改成指标或删
  • 出现被禁止章节了吗？命中→删

链路

  • 工程约束基线：.cursor/rules/core-principles.mdc
  • 配置治理基线：.cursor/rules/configuration-management.mdc
  • 项目架构 rule（如已建立）：.cursor/rules/<project>-architecture.mdc
  • README 撰写：writing-readme
  • 部署 / 坑点档案撰写：writing-pitfall-archive
  • 跨项目工程经验：writing-engineering-playbook

Gives 0 of the 12 instructions most docs writing skills give

Counted across 1,637 of the 3,044 authors here whose files we hold, read 2026-08-06

  • announce the skill at startin 54 of 1637, across 21 files
  • convert legacy doc files before editingin 45 of 1637, across 7 files
  • predict questions readers might askin 42 of 1637, across 3 files
  • Generate clarifying questions for initial contextin 42 of 1637, across 3 files
  • Create document scaffold with placeholder textin 42 of 1637, across 3 files
  • Brainstorm content options for each sectionin 42 of 1637, across 3 files
  • Test document with fresh context-less instancein 42 of 1637, across 3 files
  • ask interview questions one at a timein 42 of 1637, across 26 files
  • include exact file paths in every taskin 42 of 1637, across 15 files
  • Apply surgical edits during refinementin 41 of 1637, across 2 files
  • Offer structured workflow or freeformin 40 of 1637, across 1 file
  • Ask for document meta-contextin 40 of 1637, across 1 file

Said here and by no other author read

  • answer only current implementation and rationale
  • delete any summary or abstract section
  • delete discussion transcripts and dialectical process
  • delete external product comparisons
  • change process tense to present tense
  • use present tense for all statements

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.