mcpField
D
document-release

document-release

github.com/borkweb開発846 回インストール3 日前に更新
リポジトリ

document-release について

document-releaseは、コードの出荷後、プルリクエストのマージ前に実行するドキュメント更新ワークフローです。コード変更と照合して文書を監査し、明確な事実誤りを修正する一方、リスクのある変更やバージョン更新は確認を求めます。

主な機能

  1. 01ベースブランチとリポジトリ状態の確認
  2. 02コード変更に基づく文書レビュー
  3. 03事実に基づく文書修正の適用
  4. 04判断を要する変更の確認
  5. 05リンクと文書間の整合性確認

活用シーン

  1. 01プルリクエストのマージ前の文書監査
  2. 02パス、件数、古い参照の更新
  3. 03リリースノートとバージョンの整合性確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/borkweb/skills --skill document-release

インストール後、Claude Code で/document-releaseを入力して読み込まれたか確認します。

詳細

ステップ 0：前提条件とベースブランチの検出

作業を始める前に、このワークフローを実行できる環境かどうかを確認してください。これらの確認により、実行中に予期しない問題が発生するのを防ぎます。

  1. Git リポジトリの確認： git rev-parse --git-dir を実行します。失敗した場合は中止し、「Not a git repository.」と表示します。
  2. gh CLI の確認： gh auth status を実行します。失敗した場合は、「gh CLI is not authenticated — PR-related steps (body update, base branch detection via PR) will be skipped. Falling back to git-only detection.」と警告します。ワークフローは続行しますが、ステップ 9 では PR 本文の更新をスキップします。
  3. 作業ツリーがクリーンか確認： git status --porcelain を実行します（-uall は使用しないでください）。ドキュメントファイル（.md、VERSION、CHANGELOG*）に未コミットの変更がある場合は、AskUserQuestion を使用してユーザーに次のように確認します。 「ドキュメントファイルに、このワークフローと競合する可能性のある未コミットの変更があります。続行しますか？」

次に、この PR の対象ブランチを特定します。以降のすべてのステップで、このブランチを「ベースブランチ」として使用します。

  1. このブランチに既存の PR があるか確認します。 gh pr view --json baseRefName -q .baseRefName 成功した場合は、出力されたブランチ名をベースブランチとして使用します。

  2. PR が存在しない場合（コマンドが失敗した場合）は、リポジトリのデフォルトブランチを検出します。 gh repo view --json defaultBranchRef -q .defaultBranchRef.name

  3. 両方のコマンドが失敗した場合は、main にフォールバックします。

リリースドキュメント：リリース後のドキュメント更新

/document-release ワークフローを実行しています。このワークフローは、/ship の実行後（コードがコミットされ、PR が存在するか、これから作成される段階）かつ PR のマージ前に実行します。担当するのは、プロジェクト内のすべてのドキュメントファイルが正確で最新であり、ユーザーに親しみやすい視点で書かれていることを確認することです。

このワークフローの大部分は自動化されています。明らかな事実の更新は直接行ってください。リスクがある判断や主観的な判断が必要な場合に限り、作業を止めて質問してください。

ドライランモード： ユーザーが「dry run」「preview」「what would change」と言った場合は、ステップ 0～2 をすべて実行します（分析と監査）。ただし、編集は適用しないでください。その代わり、予定されている変更をすべてファイルごとに整理し、自動更新かユーザーへの確認事項かを分類した構造化プレビューを出力します。その後、作業を止めて「これらの変更を適用しますか？それとも計画を調整しますか？」と確認します。ユーザーが承認した場合は、計画に従ってステップ 3 以降を続行します。計画の調整を希望した場合は、そのフィードバックを反映して、プレビューを再度提示します。

作業を止めるのは次の場合に限ります：

  • リスクがある、または疑義のあるドキュメント変更（物語的な記述、理念、セキュリティ、削除、大規模な書き換え）
  • VERSION の更新判断（まだ更新されていない場合）
  • 新しい TODOS 項目の追加
  • ドキュメント間の矛盾が物語的なものの場合（事実に関するものではない場合）

次の場合は作業を止めないでください：

  • diff から明らかな事実の修正
  • 表やリストへの項目の追加
  • パス、件数、バージョン番号の更新
  • 古くなった相互参照の修正
  • CHANGELOG の文体調整（軽微な表現の調整）
  • TODOS の完了済み項目への変更
  • ドキュメント間の事実の不整合（例：バージョン番号の不一致）

絶対に行わないこと：

  • CHANGELOG の項目を上書き、置換、再生成しないでください。内容をすべて保持し、表現の調整だけを行います。
  • 確認せずに VERSION を更新しないでください。バージョン変更には必ず AskUserQuestion を使用します。
  • CHANGELOG.md に Write ツールを使用しないでください。必ず、正確な old_string に一致する文字列を指定して Edit を使用します。

ステップ 1：事前確認と差分の分析

  1. 現在のブランチを確認します。ベースブランチにいる場合は、中止します：「ベースブランチにいます。フィーチャーブランチから実行してください。」

  2. 変更内容のコンテキストを収集します。

git diff <base>...HEAD --stat
git log <base>..HEAD --oneline
git diff <base>...HEAD --name-only

  1. Glob ツールを使って、リポジトリ内のドキュメントファイルをすべて見つけます（find は使いません）。

    • プロジェクトのルートで **/*.md を検索し、その後 .git/、node_modules/、vendor/ のパスを除外します。
    • まず最上位と 1 階層下のファイルに注目します。これらが主要なドキュメントです。さらに深い階層にあるファイルは、自動生成されたものか、重要度が低いものがほとんどです。

  2. 変更内容をドキュメントに関連するカテゴリに分類します。

    • 新機能 — 新しいファイル、新しいコマンド、新しいスキル、新しい機能
    • 動作の変更 — サービスの変更、API の更新、設定の変更
    • 機能の削除 — ファイルの削除、コマンドの削除
    • インフラストラクチャ — ビルドシステム、テストインフラストラクチャ、CI

  3. 簡潔な概要を出力します：「M 件のコミットで変更された N 個のファイルを分析しています。レビュー対象のドキュメントファイルが K 個見つかりました。」

ステップ 2：ファイルごとのドキュメント監査

各ドキュメントファイルを読み、差分と照合します。

README.md：

  • 差分に見られるすべての機能と能力について説明されていますか？
  • インストールやセットアップの手順は変更内容と一致していますか？
  • 例、デモ、使用方法の説明は引き続き有効ですか？
  • トラブルシューティングの手順は引き続き正確ですか？

ARCHITECTURE.md：

  • ASCII 図とコンポーネントの説明は現在のコードと一致していますか？
  • 設計上の判断や「理由」の説明は引き続き正確ですか？
  • 差分によって明確に否定される内容だけを更新してください。

CONTRIBUTING.md — 新規コントリビューター向けの動作確認：

  • 初めてコントリビューターになるつもりで、セットアップ手順を実行します。
  • 記載されたコマンドは正確ですか？各手順は成功しますか？
  • 初めて参加する人が失敗したり、混乱したりする箇所があれば指摘します。

CLAUDE.md / AGENTS.md / プロジェクトの指示：

  • プロジェクト構成のセクションは実際のファイルツリーと一致していますか？
  • 記載されたコマンドやスクリプトは正確ですか？
  • ビルドやテストの手順は設定ファイルの内容と一致していますか？

その他の .md ファイル：

  • ファイルを読み、その目的と対象読者を判断します。
  • 差分と照合し、ファイル内の記述に矛盾がないか確認します。

インラインおよび生成されたドキュメント： コードレベルのドキュメントは、Markdown ドキュメントとの整合性が失われがちです。差分に公開 API の変更が含まれる場合は、次の項目が古くなっていないか確認します。

  • PHPDoc / JSDoc / docblock — 差分で関数シグネチャ、戻り値の型、動作が変更された場合は、対応する docblock が引き続き一致しているか確認します。変更されたファイル内で @param、@return、@throws を検索するには Grep を使います。
  • OpenAPI / Swagger の仕様 — API エンドポイントが追加、変更、削除された場合は、openapi.yaml、swagger.json、または類似の仕様ファイルが存在し、更新が必要か確認します。**/openapi.*、**/swagger.* を見つけるには Glob を使います。
  • README のバッジ／自動生成されたセクション — リポジトリでバッジ（カバレッジ、バージョン、ビルドステータス）を使用している場合は、正しい値を参照し続けているか確認します。セクションが自動生成されると明記されている場合（例：``）、編集せずに指摘します。手作業で編集するのではなく、ツールで再生成する必要があります。

これらは補足的な確認です。すべてのソースファイルを詳しく調べる必要はありません。差分に含まれ、公開ドキュメントに影響するファイルに注目します。

各ファイルについて、必要な更新を次のように分類します。

  • 自動更新 — 差分から明らかに必要と判断できる事実の修正：表への項目追加、ファイルパスの更新、件数の修正、プロジェクト構成ツリーの更新。
  • ユーザーに確認 — 説明文の変更、セクションの削除、セキュリティモデルの変更、大規模な書き換え（1 つのセクションで約 10 行超）、関連性が曖昧な変更、まったく新しいセクションの追加。

ステップ 3：自動更新を適用する

明確で事実に基づく更新はすべて、Edit ツールを使って直接適用します。

変更したファイルごとに、具体的に何を変更したかを説明する1行の要約を出力します。単に「README.md を更新」ではなく、「README.md：スキル一覧に /new-skill を追加し、スキル数を 9 から 10 に更新」のように記載します。

自動更新しない項目：

  • README の導入部分やプロジェクトの位置付け
  • ARCHITECTURE の理念や設計上の根拠
  • セキュリティモデルの説明
  • ドキュメント内のセクション全体を削除しない

ステップ 4：リスクのある変更や判断が難しい変更について確認する

ステップ 2 で特定したリスクのある更新や判断が難しい更新ごとに、AskUserQuestion を使い、次の情報を含めます。

  • コンテキスト：プロジェクト名、ブランチ、対象ドキュメントファイル、確認する内容
  • 具体的なドキュメント上の判断
  • RECOMMENDATION: [X] を選択してください。理由：[一行で説明]
  • C) Skip — 現状のままにする、を含む選択肢

回答のたびに、承認された変更をただちに適用します。

ステップ 5：VERSION の更新を確認する

VERSION の確認は CHANGELOG の文面調整より先に行います。この段階でユーザーがバージョンを上げた場合、後続のステップで CHANGELOG の記載やドキュメント間の整合性を確認する際に、正しいバージョン番号を反映できるためです。

重要 — 必ず確認を取ってから VERSION を更新してください。

  1. VERSION が存在しない場合： 何も言わずにスキップします。

  2. このブランチで VERSION がすでに変更されているか確認します。

git diff <base>...HEAD -- VERSION

  1. VERSION がまだ更新されていない場合： AskUserQuestion を使います。

    • RECOMMENDATION: ドキュメントのみの変更でバージョンを上げる必要はほとんどないため、C（スキップ）を選択してください
    • A) PATCH を上げる — ドキュメントの変更をコードの変更と同時にリリースする場合
    • B) MINOR を上げる — 重要な単独リリースの場合
    • C) Skip — バージョンの更新は不要

  2. VERSION がすでに更新されている場合： その更新で変更範囲全体がカバーされているか確認します。カバーされていない重要な変更がある場合は、さらに更新するか、既存のバージョンに含めるかを確認します。

ステップ 6：CHANGELOG の文面を整える

重要 — CHANGELOG の項目を絶対に上書きしないでください。

このステップでは文面を整えます。CHANGELOG の内容を書き換えたり、置き換えたり、再生成したりはしません。

ルール：

  1. まず CHANGELOG.md 全体を読みます。すでに記載されている内容を把握してください。
  2. 既存の項目内の表現のみを変更します。項目の削除、並べ替え、置き換えはしないでください。
  3. CHANGELOG の項目を一から再生成しないでください。その項目は実際の差分とコミット履歴に基づいて書かれており、信頼できる情報源です。行うのは文章の調整であり、履歴の書き換えではありません。
  4. 項目に誤りや不足があるように見える場合は、AskUserQuestion を使います。黙って修正しないでください。
  5. 正確な old_string の一致を指定して Edit ツールを使います。Write を使って CHANGELOG.md を上書きしないでください。

このブランチで CHANGELOG が変更されていない場合： このステップをスキップします。

このブランチで CHANGELOG が変更されている場合： 項目の文体を確認します。

  • 魅力の確認： 各箇条書きを読んだユーザーが「いいですね、試してみたい」と思うでしょうか。そうでない場合は、内容ではなく表現を書き換えます。
  • 実装の詳細ではなく、ユーザーが新たにできるようになったことから書き始めます。
  • 「リファクタリングしました」ではなく、「〜できるようになりました」と書きます。
  • コミットメッセージのように読める項目があれば指摘し、書き換えます。
  • 内部向け・コントリビューター向けの変更は、独立した「### コントリビューター向け」サブセクションに記載します。
  • 軽微な文体の調整は自動で行います。書き換えによって意味が変わる場合は、AskUserQuestion を使います。
  • ステップ 5 で VERSION を更新した場合は、CHANGELOG の項目に正しいバージョンが記載されていることを確認します。

ステップ 7：ドキュメント間の整合性、リンク、見つけやすさの確認

各ファイルを個別に監査した後、ドキュメント間の整合性を確認します。

  1. README の機能／能力の一覧は、CLAUDE.md／AGENTS.md の記述と一致していますか？
  2. ARCHITECTURE のコンポーネント一覧は、CONTRIBUTING のプロジェクト構成の説明と一致していますか？
  3. CHANGELOG の最新バージョンは VERSION ファイルと一致していますか？
  4. 見つけやすさ： すべてのドキュメントファイルに README.md または CLAUDE.md からたどり着けますか？ARCHITECTURE.md が存在するのに、README と CLAUDE.md のどちらからもリンクされていない場合は、そのことを指摘してください。すべてのドキュメントは、いずれかのエントリーポイントファイルから見つけられる必要があります。
  5. ドキュメント間の矛盾をすべて指摘してください。明確な事実の不一致（例：バージョンの不一致）は自動修正してください。記述上の矛盾には AskUserQuestion を使用してください。
  6. 内部リンクの確認： すべてのドキュメントファイルを対象に、相対リンクをスキャンしてください。[Architecture](./ARCHITECTURE.md) のようなファイルリンクと、[see setup](#setup) のようなアンカーリンクの両方が対象です。ファイルリンクについては、Glob を使ってリンク先ファイルの存在を確認してください。アンカーリンクについては、リンク先ファイルに対象の見出しが存在することを確認してください。diff にファイル名の変更、削除、見出しの変更が含まれる場合は、特に重要です。リンク先が明らかに変更されている場合は、壊れたファイルリンクを自動修正してください（名前の変更を検出するには git diff --diff-filter=R を使用します）。意図するリンク先が明確でない場合は、AskUserQuestion を使用してください。

ステップ 8：TODOS.md の整理

TODOS.md が存在しない場合、このステップはスキップします。

  1. 完了済みなのに未チェックの項目： diff と未完了の TODO 項目を照合してください。このブランチの変更によって TODO が明らかに完了している場合は、**Completed:** vX.Y.Z (YYYY-MM-DD) を付けて Completed セクションに移動します。慎重に判断し、diff に明確な根拠がある項目だけを完了扱いにしてください。

  2. 説明の更新が必要な項目： TODO が大幅に変更されたファイルやコンポーネントを参照している場合、説明が古くなっている可能性があります。TODO を更新するか、完了扱いにするか、そのままにするかを確認するため、AskUserQuestion を使用してください。

  3. 新たに先送りされた作業： diff 内の TODO、FIXME、HACK、XXX コメントを確認してください。重要な先送り作業を示すもの（単なる短いインライン注記ではないもの）については、それぞれを TODOS.md に記録するかどうか尋ねるため、AskUserQuestion を使用してください。

ステップ 9：コミットと出力

まず変更がないか確認： git status を実行します（-uall は絶対に使用しないでください）。前のステップでドキュメントファイルが変更されていない場合は、「すべてのドキュメントは最新です。」と出力し、コミットせずに終了してください。

コミット：

  1. 変更したドキュメントファイルを、ファイル名を指定してステージングします（git add -A と git add . は絶対に使用しないでください）。
  2. ステップ 3～6 で作成した1行の要約をもとに、説明的なコミットメッセージを作成します。変更内容の経緯が git log でわかるよう、要約をコミット本文にまとめてください。「ドキュメントを更新」のような内容だけにしないでください。例：
git commit -m "$(cat <<'EOF'
docs: update documentation to match shipped changes

- README.md: added /new-skill to skills table, updated skill count from 9 to 10
- ARCHITECTURE.md: updated component diagram to reflect new service layer
- CHANGELOG.md: polished voice for v2.3.0 entry

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

件名は72文字未満にしてください。変更した各ファイルについて、1行の要約を本文に箇条書きで記載します。変更ファイルが1つだけの場合は、件名のみで構いません。

  1. 現在のブランチにプッシュします。
git push

PR 本文の更新（PR が存在する場合）：

  1. 既存の PR 本文を一時ファイルに読み込みます（衝突を避けるため mktemp を使用します）。
PR_BODY_TMP=$(mktemp /tmp/pr-body-XXXXXX.md)
gh pr view --json body -q .body > "$PR_BODY_TMP"

  1. 本文に ## Documentation セクションがすでにある場合は置き換えます。ない場合は末尾に追加します。ドキュメント差分のプレビューを含め、変更した各ファイルについて、具体的な変更内容を説明してください。

  2. 書き戻して、一時ファイルを削除します。

gh pr edit --body-file "$PR_BODY_TMP"
rm -f "$PR_BODY_TMP"
  1. gh pr view が失敗した場合（PR が存在しない場合）は、「PR が見つかりません。本文の更新をスキップします。」と出力してスキップします。

構造化されたドキュメント健全性の概要（最終出力）：

Documentation health:
  README.md       [status] ([details])
  ARCHITECTURE.md [status] ([details])
  CONTRIBUTING.md [status] ([details])
  CHANGELOG.md    [status] ([details])
  TODOS.md        [status] ([details])
  VERSION         [status] ([details])

status は次のいずれかです。

  • Updated — 変更内容の説明
  • Current — 変更不要
  • Voice polished — 表現を調整
  • Links fixed — 壊れたリンクを修正
  • Not bumped — ユーザーが更新を見送った
  • Already bumped — バージョンは /ship によって設定済み
  • Skipped — ファイルが存在しない

（ステップ 0 で検出した）gh が利用できなかった場合は、概要に「PR 本文の更新をスキップ（gh は認証されていません）」と記載します。

重要なルール

  • 編集前に読む。 変更する前に、必ずファイルの内容をすべて読みます。
  • CHANGELOG を上書きしない。 表現の調整のみ行います。エントリーを削除、置換、再生成してはいけません。
  • VERSION を黙って更新しない。 必ず確認します。
  • 変更内容を明確にする。 編集ごとに、変更内容を1行で要約します。
  • プロジェクト固有ではなく、汎用的なヒューリスティックを使う。 監査はどのリポジトリでも機能するものとします。
  • 見つけやすさを重視する。 すべてのドキュメントファイルに、README または CLAUDE.md からアクセスできるようにします。
  • 語調：親しみやすく、ユーザーを第一に考え、わかりやすく。 コードを見たことがない聡明な人に説明するように書きます。

コメント

Markdown 対応