cognitive-doc-design

使用する場面

読者がすばやく理解し、内容を記憶に留め、レビュー時に活用する必要があるドキュメントを作成または編集するときに、このスキルを読み込みます。

特に、次のような場合に使用します。

• PR の説明とレビューコメント。
• コントリビューターまたはメンテナー向けのガイド。
• アーキテクチャ、ワークフロー、オンボーディングに関するドキュメント。
• 現在、長すぎる、内容が詰め込まれている、または流し読みしにくいと感じるドキュメント。

重要なパターン

パターン	ルール
結論から始める	決定事項、アクション、結果を最初に示します。背景はその後に続けます。
段階的に情報を示す	まず基本的な手順を示し、その後に詳細、例外的なケース、参考情報を追加します。
情報を小分けにする	関連情報を小さなセクションにまとめます。階層のないリストは短く保ちます。
道しるべを示す	見出し、ラベル、コールアウト、要約を使い、読者が現在どこにいるか把握できるようにします。
思い出すより見て分かるようにする	記憶しておく必要のある文章よりも、表、チェックリスト、例、テンプレートを優先します。
レビュアーへの配慮	ストーリー全体を再構成しなくても、レビュアーが意図を確認できるようにドキュメントを作成します。

ドキュメントの構成

リポジトリに、より適したテンプレートが用意されていない場合は、次の標準的な構成を使用します。

# <Outcome-oriented title>

<One paragraph: what changed, who it helps, and why it matters.>

## Quick path

1. <First action>
2. <Second action>
3. <Verification or expected result>

## Details

| Topic | Decision |
|-------|----------|
| <area> | <concise explanation> |

## Checklist

- [ ] <Reader can confirm this>
- [ ] <Reader can confirm that>

## Next step

<Link or action that continues the workflow.>

PR とレビュー用ドキュメント

PR を記録する際は、レビューの進め方を明確にして、レビュアーの疲弊を軽減します。

• 何を最初にレビューするかを明記します。
• 意図的に対象範囲から除外した内容を明記します。
• 作業が複数の PR に分かれている場合は、前後の PR にリンクします。
• 各セクションでは、1 つの決定事項または作業単位に焦点を当てます。
• 受け入れ基準と検証には、チェックリストを使用します。

コマンド

# Check markdown files changed in the current branch
git diff --name-only -- '*.md'

# Inspect PR changed-line count for cognitive load
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles