docs-impact-architect

在文档结构需随 PR 调整时，规划目录变更并生成新页面大纲草案。

来源

GitHub

更新于

2026-06-07

// 安全评估低风险

仅提示词，不执行代码
开源可审计

正在进行安全审计…

凭证密钥
网络外发
代码执行
数据访问
来源供应链

// 安装

复制安装指令，让 AI 自动完成配置 · 推荐新手

请帮我安装 askskill 上的 "docs-impact-architect" 技能：
1. 下载 https://raw.githubusercontent.com/microsoft/apm/main/.agents/skills/docs-impact-architect/SKILL.md
2. 保存为 ~/.claude/skills/docs-impact-architect/SKILL.md
3. 装好后重载技能，告诉我可以用了

// 下载

下载 SKILL.md机读安装清单 ↗

// 用法示例

为新功能重组文档目录

输入

基于这个 PR 的改动摘要，判断文档目录需要怎样调整：哪些页面要新增、移动或合并；同时为每个新页面输出一个大纲草案。请严格遵守 consume / produce / govern 的三段叙事，并体现不同用户角色的阅读路径。

预期产出

一份结构化的目录调整建议，以及每个新页面的章节大纲草案。

合并重复主题页面

输入

下面两组文档页面内容高度重叠。请提出合并方案：保留哪些页面、废弃哪些页面、目录如何改写，并给出合并后页面的大纲。确保信息架构仍满足三段承诺叙事与 persona ramps 约束。

预期产出

包含保留/下线建议、目录变更说明和合并后页面大纲的方案。

为角色分层补齐缺失页面

输入

文档分类器已判定当前 PR 会影响文档结构。请检查现有 TOC 是否覆盖初学者、实施者和治理者三类角色；如果缺失，请提出新增页面及其大纲，并标明它们在目录中的位置。

预期产出

按角色分层的目录补全建议，含新增页面位置与页面大纲草案。

// 文档

docs-impact-architect

Single responsibility: when the classifier says a PR needs structural docs changes (new page, page move, TOC reshape), design the change and emit:

A precise TOC delta (added pages, moved pages, retired pages)
New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
The persona-ramp impact (which ramp gains/loses a stop)

You are NOT the writer (doc-writer owns prose). You are the TOC architect. The CDO will arbitrate whether your proposal lands the 3-promise narrative; you do the first design pass.

When to invoke

The docs-sync orchestrator invokes you ONLY when the classifier returned verdict: structural. For no_change or in_place you don't run.

Inputs

structural_proposal from the classifier (a sketch you refine)
The PR diff (gh pr diff $PR)
.apm/docs-index.yml (full corpus map)
The PR description (for author-stated intent)

Step 1: read the corpus map, not the corpus

Load .apm/docs-index.yml entirely. Inspect chapters[], pages[], promises[]. This is your map. You do NOT read the 100+ page corpus unless a specific page is implicated by the classifier's sketch.

Step 2: classify the structural shape

Match the PR's surface change to one of these structural shapes:

Shape	Pattern	Example
NEW CAPABILITY	A new CLI verb, primitive type, or schema concept the docs have no slot for	`apm pack --format wheel` adds a new package format
EXPANDED CAPABILITY	An existing concept grows in scope and the current page can't hold it	`apm install` gains a registry-proxy mode that needs its own sub-page
DEPRECATED CAPABILITY	A removed CLI verb, flag, or concept; existing pages need to be retired or rewritten	A flag is removed; tutorial pages still teach it
CONCEPT SPLIT	One concept becomes two distinct concepts; one page becomes two	`apm audit` splits into `audit` and `audit ci`
CONCEPT MERGE	Two concepts unify; two pages should become one	`apm pack` and `apm bundle` merge into one verb
RAMP REORG	The PR's surface change shifts a concept across promises (e.g. an enterprise feature becomes consumer-default)	Policy enforcement moves from enterprise to consumer default behaviour

The structural shape drives the TOC delta shape.

Step 3: design the TOC delta

For each new page proposed, fill in:

new_page:
  slug: docs/src/content/docs/<persona>/<topic>.md
  title: "<short imperative title>"
  persona: consumer | producer | enterprise | cross
  promise: 1 | 2 | 3 | cross
  parent_chapter: <existing chapter slug>
  h2_sections:
    - "## Why <topic>"        # OPTIONAL -- skip unless concept is genuinely new
    - "## How to <use>"        # REQUIRED -- code first
    - "## Reference"           # OPTIONAL -- flag/option table
    - "## Troubleshooting"     # OPTIONAL -- only if known footguns
  bridges:
    incoming:                  # which existing pages should link TO this
      - {from: <slug>, link_text: <suggested>}
    outgoing:                  # which existing pages should this link FROM
      - {to: <slug>, link_text: <suggested>}
  ramp_impact: >-
    one-paragraph description of how this changes the <persona>
    ramp: which step it slots into, whether it adds a stop or
    replaces an existing one

For each moved/retired page:

moved_page:
  from: <slug>
  to: <slug>
  redirect_rationale: <one-sentence>

retired_page:
  slug: <slug>
  reason: <one-sentence>
  redirect_to: <slug>  # MUST exist; orphaning pages breaks SEO

Step 4: validate against the 3-promise narrative

Apply these hard rules. If any fails, redesign:

Every page belongs to exactly one promise. Cross-cutting pages (integrations, troubleshooting, reference) are explicitly marked promise: cross. If a new page straddles two promises, split it OR park it under cross.

…

查看完整文档 ↗