document-rebuild: 文書形式と目的に合わせて組み直し、読み手が理解し納得できるかを確かめる（#2086） #2086

何をしたいか

document-restructuring を、文書の形式（Markdown・スライド・表計算・Google ドキュメント・Confluence など）と目的（決議依頼・議論・アジェンダ・小説・エッセイ・ブログ・作業レポート・論文など）に関わらず、AI が作った文書を人が読みやすく分かりやすい形へ組み直せる Skill にする。

MVV（利用者の指定 2026-10-24）

• Mission: AI が作るすべてのドキュメントを、人間が読みやすく分かりやすいドキュメントに再構築する
• Vision: この Skill に基づいて再構成するだけで、読む人が内容を完全に理解し、納得できるドキュメントになる
• Value（作成時の条件）
  1. markdown-writing など他のドキュメント系 Skill が求めていることは、原則すべて満たす
  2. 様々な文書形式に適用できる（markdown・slide・sheets・docs・confluence など）
  3. 文書形式そのものへの適用は他の Skill に任せてよい（呼び出してよい）。ただし形式によって適切な文章量やタイトルの付け方が違うことに注意する
  4. 文書の目的（決議依頼・議論・アジェンダ・小説・エッセイ・ブログ・作業レポート・論文など）に合った構成と文章量にする
  5. 形式と目的に関わらず守るべきことは、共通ルールとして定義する
  6. document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 を参照する。他の Issue 等も参照して、課題があれば取り込む

依頼（原文）

ドキュメント再構成Skill /ndf:document-restructuring を改善します

• Mission: AIが作るすべてのドキュメントを人間が読みやすく、分かりやすいドキュメントに再構築する
• Vision: このSkillに基いてドキュメントを再構成するだけで、読む人が完全に内容を理解し、納得できるドキュメントになる
• Value: (以下に基いて作成すること)

作成時にお願いしたいこと

• /ndf:markdown-writing など他のドキュメント系Skillで求めていることは原則全て満たすこと
• 様々な文書形式に適用可能であること markdown, slide, sheets, docs, confluenceなど。
• 文書形式自体への適用は他のSkillに任せる(or呼び出す)のでよい。ただ、文書形式によって適切な文章量やタイトル付けなどは異なることには注意
• 文章の目的(決議依頼、議論、アジェンダ、小説、エッセイ、ブログ、作業レポート、論文、、、)によって適切な構成や文章量であること
  • 文書形式や目的に関わらず共通して守るべきことは共通項として定義する
  • document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 も参照
• 他のissue等も参照して課題があれば取り込むこと

（書き手: 利用者、日付: 2026-10-24、/goal の起動指示）

パスの直後は半角スペースを置く（全角の括弧・句読点を密着させない）
これはMarkdownやvscode、slack表示時にリンクとして認識できるようにするためです。手段が目的化しています。

development-workflow document-types などdocument-*は名称を変更するか、スラッシュコマンドとして呼ばれないようにしてください。
/ndf:document-restructuring の呼び出しがめんどくさいです。

（「名称を変更する」「スラッシュコマンドとして呼ばれないようにする」は両方を採る、と利用者が選んだ）

短くしてもよいが、documentから始めたいです。

あと、markdown-writing は廃止か、名前を変更したい。markdownあまり関係ないし、他のドキュメント系skillと揃ってないので

（書き手: 利用者、日付: 2026-10-24、設計 Pull Request #2088 のクロスレビュー中の指示。続けて利用者が選んだ: markdown-writing は document-style へ改名して残しスラッシュコマンドの一覧から隠す、組み直しの Skill の新しい名前は document-rebuild）

issues/issue-2086-design.md
鍵の語
相変わらず直訳だなあ。こういうのをなくしたいのですが。

出力の形
共通項
形の参照
も、用語として変です。

目的の参照 もか

（書き手: 利用者、日付: 2026-10-24、設計文書の用語への指摘。語は「キーワード」「文書形式」「共通ルール」「形式別ガイド」「目的別ガイド」へ置き換えた）

設計のテンプレートの決まり（「今の問題 → 直した後」）自体が読みづらいです。最初のタイトルの方がいくらかまし

（書き手: 利用者、日付: 2026-10-25。続けて利用者が選んだ: 題の決まりの見直しを #2086 に含める、この Issue と設計 Pull Request の題は「document-rebuild: 文書形式と目的に合わせて組み直し、読み手が理解し納得できるかを確かめる（#2086）」）

今の Skill の問題（起票時に読んだ範囲）

取り込む Issue

• document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 — 議論・提案のための文書に「結論を最初の章に置く」構成が当てはまり、提案が決定に読める
• 社外向けの文書で、題と鍵になる語が公式ドキュメントの語かを確かめる手順が無く、公式に無い語がリリースの直前まで残る #2080 — 社外向けの文書で、題と鍵になる語が公式ドキュメントの語かを確かめる手順が無い
• markdown-writing と document-restructuring を統合する（別々に掛けると往復が生じる） #469 — markdown-writing と document-restructuring を統合する（規約の二重と往復）

材料（利用者がこれまでに文書について指摘したこと）

• 文書は具体例から始める。抽象語だけで進めると通じない
• 直訳の和語を避け、業界の語を優先する（道具→Tool・枚→ページ・課題→Issue）。1 語 1 意味
• スライドはスライドらしい語で書き、章扉を入れる。台本の文を縮めて載せない。1 ページ 1 メッセージ（スライドを作る実務の手順（生成スクリプト・ページの枠組み・トーン＆マナー・構成メモ・gws での変換と確認）を Skill に取り込む #2065）
• 判断を求める前に、事実・根拠・得失・推奨を本文で先に示す。経緯・前提を先に示し、内部用語を前提にしない
• パス・URL は、表示先（Markdown・VS Code・Slack など）でリンクとして認識される形で書く。全角の括弧・句読点を密着させず半角スペースを置くのはその手段（2026-10-24 の利用者の指摘: 「手段が目的化しています」）

起票者の推定

題と「今の Skill の問題」「取り込む Issue」「材料」の節は、起票者（/goal を受けた conductor）が書いた。利用者の原文に無く、起票者が推して足した条件を次に並べる。

目的

• AI が書き上げた文書を、文書形式（Markdown・スライド・表計算・文書・ページ）と文書の目的（決議依頼・議論・アジェンダ・小説・エッセイ・ブログ・作業レポート・論文など）に合った構成と文章量へ、1 つの Skill で組み直せるようにする
• 形式と目的に関わらず守る決まりを共通ルールとして 1 か所に定め、他の文書系 Skill の規約と二重にしない
• 組み直した文書を読む人が、問い直さずに内容を理解し、納得できる状態にする（Vision）

前提

• 前提 1: 文書形式の分け方は、既存の release の form-*.md と design の layout-*.md の 4 つ（文書・ページ・スライド・表計算）に、リポジトリの Markdown（docs/・課題・Pull Request の本文・設計文書）を足した 5 つを出発点にする。Confluence と Notion は形ではなく置き場（document-systems のシステム）で、形は「ページ」に当たる。分け方を変えるかは設計で決める
• 前提 2: 小説・エッセイ・ブログのように、NDF の工程（documentation モード）の外で書かれる文書も対象に含める。工程の中で呼ばれたときと、利用者が明示して呼んだときの両方で同じ手順が使える
• 前提 3: 文書の目的の一覧は利用者の挙げた 8 つを最低限とし、既存の文書タイプ（development-workflow の references/document-types.md の 6 つ）と「確定事項を伝える文書」（確定した設計・報告書。今の構成が当たるもの）を含める。目的と文書タイプの対応は設計で決める
• 前提 4: 目的ごとの文章量・形式ごとの目安で実測が無いものは、根拠を「未実測」と書いて目安を置く。実測のあるものだけを実測と書く（Value 3）
• 前提 5: 小説・エッセイ・論文などで、ビジネス文書の決まり（結論を先に置く・対比を表にする など）が目的に合わない場合は、目的の側の決まりが優先する。共通ルールはこの場合でも外さない決まりだけを持つ
• 前提 6: 組み直しは内容を足さないという今の決まりを保つ。目的に必要な章が欠けていると分かったら、控えて報告に残し、組み直しの中では書き足さない

対象範囲

含む:

• document-restructuring の手順・構成・測る指標と目安・他の Skill との境界の書き直し
• 文書形式ごと・文書の目的ごとの参照ファイル（references/ の下。対象に当たるファイルだけを読む形）の追加
• 形式と目的に共通する決まり（共通ルール）の定義
• document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083・社外向けの文書で、題と鍵になる語が公式ドキュメントの語かを確かめる手順が無く、公式に無い語がリリースの直前まで残る #2080・markdown-writing と document-restructuring を統合する（別々に掛けると往復が生じる） #469 の受け入れ条件（下の受け入れ条件 13〜21）
• 規約の二重を解くために、markdown-writing・document-drafting・design/references/layout-slide.md・release/references/form-slide.md などの該当する行を、正本を指す形へ書き換えること
• development-workflow の工程表の「ドキュメント再構成」の行の書き直し（markdown-writing と document-restructuring を統合する（別々に掛けると往復が生じる） #469 の掛け忘れ）
• 形式と目的の違う文書 3 本以上での試行（前後の値の表）

含まない:

• 文書形式への生成そのもの（pptx・Google ドキュメント・表計算の作成、Notion・Confluence への投稿）。release の form-*・document-systems・notion-writing の手順は変えない
• 版面の点検（layout-review の手順）を変えること
• 文書の内容の誤りを直すこと・内容を書き足すこと（組み直しの外の作業）
• 文書の規約の点検をスクリプトにすること（markdown-writing / document-restructuring / document-sources / notion-writing / document-drafting: セルフチェックと測定を doc-check の呼び出しにする #873・基盤: Markdown の文書検査を配布される 1 本のツールにする（doc-check） #854 は「やらない」で閉じている）
• 既存の文書を新しい Skill で一括に組み直すこと
• .md の文言を照合するテストを書くこと（AGENTS.md）

ドメインイベント

用語

（「目的」は requirements-design の references/document-requirements.md で「読み手が読み終えた後にどうなるか」の意味に使われている。この変更では「文書の目的」と呼んで分ける。どちらかへ寄せるかは設計で決める）

受け入れ条件

共通ルール（Value 5）

• 1. document-restructuring が、文書形式と文書の目的に関わらず守る決まりを「共通ルール」として 1 か所に一覧で持つ。各行に、その決まりの正本の場所（その Skill 自身か、他の Skill のファイルと節）を書く。利用者がこれまでに指摘した 5 つ（具体例から始める・直訳の和語を避け業界の語で 1 語 1 意味・判断を求める前に経緯と前提と材料を示す・内部用語を前提にしない・パス・URL を表示先でリンクとして認識される形で書く）について、共通ルールに採るか、形式か目的別ガイドへ置くか、採らないかと理由が設計文書の決定の記録にある

他の文書系 Skill の規約（Value 1）

• 2. document-restructuring が、文書系の Skill と参照（markdown-writing・document-drafting と type-*.md・notion-writing・layout-review・decision-request・document-sources・document-systems・design/references/layout-*.md・release/references/form-slide.md・form-document.md・form-spreadsheet.md・form-page.md・development-workflow/references/document-types.md）のそれぞれについて、何を求めるか・組み直しのどの手順で読むか（または読まない理由）を表で持つ。表に無い文書系 Skill が 0 件である
• 3. 組み直した後の文書が、当たる他の Skill の求める節と決まりを失わない。少なくとも次を手順が守る: design の設計文書の固定の章（今の決まり）、document-drafting の文書タイプの「必ず書く節」、decision-request の 5 項目（判断を求める文書のとき）、document-sources の出典の節
• 4. 文書形式を決める手順があり、手がかり（拡張子・置き場・呼び出し元の指定）で決まらないときは推測せずに呼び出し元へ確かめる

文書形式（Value 2・3）

• 5. 文書形式ごとに、1 つの参照ファイル（references/ の下）がある。各ファイルは、文章量の単位と目安（スライドは 1 ページ、表計算は 1 シートと 1 セル、ページと文書は章、など）・題と見出しの付け方・その形式への適用を担う Skill（呼び出し先）を持つ。手順は対象の形のファイルだけを読む（lang-*.md と同じ形）。形式への適用そのもの（生成・投稿・版面）の手順は書かず、呼び出し先を指す
• 6. 測る指標と目安が文書形式ごとに分かれ、各目安に根拠（実測の出所か「未実測」）が添えられている。章あたりの行数・平均文長のように形に当たらない指標は、その形で測らないと明記されている
• 7. スライドの形式別ガイドが、design/references/layout-slide.md と release/references/form-slide.md の「ページの文言」「章立て」（1 ページ 1 メッセージ・台本の文を縮めて載せない・章扉・見出しはページの結論）と食い違わず、同じ決まりを書き写さずに正本を指す

文書の目的（Value 4）

• 8. 文書の目的を決める手順があり、手がかり（題・本文・Pull Request の語、確認待ちの問いの有無、承認欄の有無など）と、決まらないときに呼び出し元へ確かめることが書かれている
• 9. 文書の目的ごとに、構成（読み手の問いの順）と文章量の目安を持つ。少なくとも、確定事項を伝える文書・議論用の文書・決議依頼・アジェンダ・作業レポート・論文・ブログ・エッセイ・小説に当たる構成がある。当たる目的が無い文書では、その場で決めた構成を記録に残す
• 10. 目的別の構成が既存の文書タイプ（6 つ）とどう対応するかが表で書かれ、document-drafting の type-*.md の「読み手が最初に問うこと」と食い違わない
• 11. 「結論・成果物が定義される位置」の指標が、目的ごとの読み替え（議論用の文書は論点、小説・エッセイは指標の対象外 など）を持つ

試行（Value 3）

• 12. 文書形式と文書の目的の組み合わせの違う文書 3 本以上（少なくとも議論用の文書 1 本・スライド 1 本・確定事項を伝える文書 1 本）へ新しい手順を掛け、それぞれの前後の値の表と、目的別の構成に従ったかの判定を設計か実装の Pull Request に残す

#2083 を閉じる行

• 13. 議論用の文書の構成が「論点 → 事実 → 事実の解釈 → 提案 → 提案の中身 → 確認すること（未決の問い） → 未確定・残リスク」である（document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 の直し方の候補 1）
• 14. 議論用の文書の見分け方が手順 1 にある（本文や Pull Request に「議論用」「案」「提案」とある、確認待ちの問いを含む など。document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 の候補 2）。指標「結論・成果物が定義される位置」の目安が、議論用の文書では「論点が最初の章」に読み替わる（document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 の候補 3）
• 15. 議論用の文書では、提案の章を決定と区別できる言い回し（「〜する案とする」「次の扱いを提案する」など）で書く決まりがあり、置き場所（document-restructuring か markdown-writing か）が 1 か所に決まっている（document-restructuring: 議論・提案のための文書にも「結論を最初の章に置く」並びが当てはまり、提案が決定に読める #2083 の候補 4）。受け入れ条件 12 の議論用の文書の試行で、組み直した後に提案が冒頭の「方針」の章として置かれていない

#2080 を閉じる行

• 16. 読み手がリポジトリの外にいる文書（社外向けの発表資料・記事・提案書など）で、題とキーワードを公式ドキュメントの語と表記に突き合わせる手順がある。手順は、確かめる語の選び方（題・見出し・繰り返し出る語）・確かめる出所（公式ドキュメントの URL）・結果の残し方（語・出所・判定）を持ち、表記の揺れ（英語とカタカナの混在など）も見る
• 17. 16 の手順の正本は 1 か所で、release/references/form-slide.md と design/references/layout-slide.md の「ページの文言」の行と document-drafting は、その正本を指す（同じ手順を写さない）。公式の出所が見つからない語は「確かめられなかった」と記録に残る

#469 を閉じる行

• 18. markdown-writing と document-restructuring で重なっていた規約（文書の長さ・対比と列挙の形・多義語）が、それぞれ正本を 1 か所だけに持ち、もう片方は正本を指す。重なりの一覧（markdown-writing と document-restructuring を統合する（別々に掛けると往復が生じる） #469 の「重なっている規約」の表）の各行で、どちらが正本かが設計文書に書かれている
• 19. 片方の規約を満たす直しがもう片方の目安を破ったときに、掛け直しを繰り返さない決まりがある（目安を超えたら理由と採らなかった直し方を残して進む、を保つ。整える手順と測り直す手順の関係が、往復の起きない順に書かれている）
• 20. 統合するか（1 つの Skill にする）、呼び出しの関係を強めるか（同時に掛ける形を足す）の案と推奨が設計文書の決定の記録にあり、選んだ側に合わせて、名前・配布の基準（plugins/ndf/manifests/*-skills.txt）・markdown-writing を単独で呼ぶ場面の扱いが揃っている
• 21. development-workflow の工程表の「ドキュメント再構成」の行から、markdown-writing の規約がその工程で掛かることが読み取れる（掛け忘れが起きない）

呼び出しやすさ（2026-10-24 の利用者の追加）

• 25. Claude Code で /ndf:doc と打ったときのスラッシュコマンドの候補が、組み直しの Skill 1 つになる。document-drafting・document-sources・document-systems ・document-style（今の markdown-writing）はスラッシュコマンドの一覧に出ず、工程と AI からは今までどおり呼べる。この発動制御の分類が plugins/ndf/skills/AUTHORING.md の「発動制御の 4 分類」の表にある
• 26. 組み直しの Skill の名前が document-rebuild になり、markdown-writing の名前が document-style になる。改名に合わせて、参照するファイル・配布の基準（plugins/ndf/manifests/*-skills.txt）・工程表・テストが新しい名前に揃い、古い名前を指す参照が 0 件である（確定仕様と過去の記録は除く）

共通ルールの書き方（2026-10-24 の利用者の指摘）

• 27. 共通ルールと、この変更で足す書き方の規則は、読み手に何が成り立つか（目的）を規則とし、手段は例として添える。パス・URL の規則は「表示先でリンクとして認識される形で書く」を規則とし、半角スペースは例である

訳語・造語を残さない（2026-10-24 の利用者の指摘）

• 28. 組み直しの手順が、形式・目的・読み手に関わらず、題・見出し・用語として立てた語・繰り返し出る語（キーワード）を確かめる。読み手が社外なら公式ドキュメントの語、社内なら用語集と読み手の業界で流通している語と突き合わせ、訳語・造語（例: key term を「鍵の語」と書く）を流通している語へ置き換える。この変更が足す Skill の本文・参照・用語集の語も、同じ確かめを通っている

読み手が理解し納得できることを確かめる（2026-10-24、承認ゲート 1 で利用者が選んだ）

• 29. 組み直しの手順が、組み直した文書を文脈を持たない読み手役（組み直した文書と想定する読み手の説明だけを渡す）に読ませ、要点の言い直し・分からなかった語と箇所・納得できなかった主張を受け取る。語と順で直せるものは直し、内容が足りないものは足すべき内容として報告に控える。受け入れ条件 12 の試行の 3 本で、その結果が報告に残る

題を読みやすくする（2026-10-25 の利用者の指摘）

• 30. 設計文書の H1 と設計 Pull Request の題の決まりが「<対象>: <直すと何ができるようになるか>」の短い 1 文（目安 60 字以内）になり、今の問題（現象）は題に入れず「目的」の章に置く。題の付け方の正本は組み直しの Skill の形式別ガイドにあり、design/references/design-template.md と development-workflow/references/approval-request.md はその正本を指す（「今の問題 → 直した後」の形の決まりは残らない）

退行しないこと

• 22. 今の 4 つの手順（測る・組み直す・整える・測り直す）・内容を足さない決まり・前後の値の表の報告・design の設計文書の固定の章を動かさない決まりが残っている
• 23. 工程名「ドキュメント再構成」と Skill の配布の基準が、既存のテスト（plugins/ndf/skills/development-workflow/tests/test_document_restructuring_stage.py など）を通る。名前を変える場合（受け入れ条件 26）は、同じ変更でテストと配布の基準を直す
• 24. SKILL.md が plugins/ndf/skills/AUTHORING.md の上限値（500 行・本文 5,000 トークン・description の文字数）に収まり、python3 scripts/check-skill-frontmatter.py が 0 で終わる。.md の文言を照合するテストを足していない

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

設計で案と推奨を決定の記録に書き、ゲート 1 で利用者が選ぶ。

進行

モード: —

• 要求と受け入れ条件 — 2026-10-24 13:13
• 作業場所の用意 — 2026-10-24 20:26
• 設計 — 2026-10-24 13:19
• 素材の収集と出典の確定
• ドキュメント再構成 — 2026-10-24 13:29
• ドキュメントレビュー
• 計画 — 2026-10-24 20:26
• 実装 — 2026-10-24 20:27
• 構造改善 — 2026-10-24 21:25
• 実装レビュー — 2026-10-24 22:14
• 完了判定 — 2026-10-24 20:49
• Pull Request — 2026-10-24 20:58
• 確定仕様化 — 2026-10-25 00:48
• 後片付け — 2026-10-25 00:43
• 配布 — 2026-10-24 22:43
• 体裁レビュー
• リリース後テスト — 2026-10-25 00:43
• 振り返り — 2026-10-25 03:32
• 棚卸し — 2026-10-25 03:33

リリース後テスト（v10.20.0）: 受け入れ条件 10 が不合格（#2113 で直す）。ほかは合格。記録: #2109 (comment)

振り返り: #2110 (comment)