agentleFS
guang-lee-cnguang-lee-cn/scaffold-skills/skills/architecture-support-brief/SKILL.md

architecture-support-brief

Skill2 starsChanged 13 days agoMITView on GitHub

按需生成“支持性说明/评审答辩包”,结论前置,不改主方案、不反向链接。触发词:展开/深挖/依据/support-brief/支持性说明/评审答辩。当用户说“展开 / 深挖 / 依据 / support-brief”时使用:把当前上下文中的争议点写成一份可独立阅读的简短支持文档,供评审人追问时解释。

The file

Files
SKILL.md

架构支持包(Architecture Support Brief)

触发词

展开、深挖、依据、支持包、support-brief。

用户只给触发词时,默认针对当前对话最后一个未收口的架构争议点;不要重新问“你想展开什么”,除非上下文确实没有主题。

铁律

  1. 不修改主架构文档,也不在主文档中加指向支持包的链接。
  2. 支持包是按需答辩材料,不是方案正文;不要把它当成新的“架构基线”。
  3. 结论前置:第一屏(30 秒)先给 3–6 条结论;细节在后。
  4. 区分 事实 / 推断 / 建议;事实带 file:line、规范章节或运行证据。
  5. 默认 1–2 页;用户要求“长版/完整版”再扩。
  6. 只回答当前上下文;缺关键输入时,只问一个问题。

输出位置

  • 默认:项目约定的 support-briefs/<topic>-<YYYY-MM-DD>.md。
  • 项目 profile 可覆盖路径;没有 profile 时放在当前文档同目录的 support-briefs/。
  • 文件名用 kebab-case + 日期;同日多版加 -v2。

文档结构(固定)

# 支持性说明:<topic>

> 性质:评审答辩支持包,不是架构方案正文;主方案不链接本文件。
> 日期 / 关联文档 / 规范依据

## 0. 30 秒结论
- 3–6 条,先回答“能不能/是不是/为什么”。

## 1. 概念与边界
- 术语表;把容易混的概念拆开(如 API 风格 vs wire mapping vs 合规点)。

## 2. 事实与证据
| 结论 | 证据 | 强度 |
- 规范条款、代码 file:line、测试/运行记录。

## 3. 为什么是这样 / 取舍
- 备选方案、被否决原因、MVP/架构约束。

## 4. 如果要求变化,影响与代价
- 要做什么、改哪层、工作量级、是否换底座。

## 5. 对外表述 / 交付口径
- 允许/不允许的说法;SBOM/合规声明/合同边界(如适用)。

## 6. 开放问题
- 需要谁拍板;没有答案时不要编。

## 7. 证据索引
- 主文档、规范、审核、ADR 的链接/行号。

写作规则

  • 先回答“是/不是/能做到/不能声明”,再解释。
  • 不用“应该/可能/大概”代替结论;不确定就标“待确认”。
  • 不把“功能可用”与“标准合规”混为一谈。
  • 不把 SBOM 当合规声明;不把 API 风格当 wire mapping。
  • 不重复主文档全文;只给评审人需要的“为什么/证据/代价”。
  • 如果支持包被多次追问,建议把稳定部分沉淀进 ADR/README,而不是无限加长。

质量自检

  • 第一屏能否在 30 秒内回答评审人的问题?
  • 每个“事实”是否有来源?
  • 是否明确“现在有什么/没有什么”?
  • 是否明确“要改变需要付什么代价”?
  • 是否没有修改主文档、没有反向链接?

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.