定期実行・自動化 2026年10月27日 9分で読めます

GitHub wikiの書き方｜AIと下書きして確かめた手順

GitHub wikiの書き方｜AIと下書きして確かめた手順

GitHub wikiの書き方がわからず、「ドキュメントを書かなきゃ」と思いながら後回しにしていませんか。

私もドキュメントを書くのは苦手で、何から書けばいいのかで手が止まります。

そこで今回、小さなサンプルツールを用意して、Claude Codeと一緒にwikiの下書きを作ってみました。この記事では、GitHub wikiの基本、実際に使ったプロンプト、下書きを確かめる方法、そして書いてみて初めて気づいたことを紹介します。

先にお伝えしておくと、今回の作業は手元のパソコン上での下書きと確認までです。GitHub上のwikiへのpushと表示確認は、まだ試せていません。その部分は公式ドキュメントをもとに書いています。

GitHub wikiの書き方は「ページ構成を先に決める」が近道

一言で言うと、いきなり本文を書くより「どんなページを作るか」を先に決めて、AIに下書きを頼むほうが進めやすいと感じました。

GitHub wikiは、リポジトリに付属するドキュメント置き場です。READMEが「最初に読む1枚」だとすると、wikiは「使い方や困ったときの情報を複数ページにまとめる場所」というイメージです。

公式ドキュメント（2026年10月時点）で確認した主なポイントは次のとおりです。仕様は変わることがあるので、使う前に公式ドキュメントも確認してください。

wikiは、GitHub Freeでは公開リポジトリで使えます。非公開リポジトリで使うにはGitHub Pro、Teamなどのプランが必要です
公開リポジトリのwikiは誰でも読めます。秘密情報は書かないようにしましょう
編集できるのは、基本的にリポジトリへの書き込み権限を持つ人です
ページはMarkdownで書けます。ファイル名がそのままページのタイトルになります
最初の1ページは、GitHubの画面上で作成する必要があります

試したこと：サンプルツールのwikiを下書きした

今回は、CSVの金額をカテゴリ別に合計する20行ほどのPythonツールを、練習用に用意しました。

ページ構成は、次の4ページ＋サイドバーにしました。

`Home.md`：トップページ。各ページへの案内
`Setup.md`：準備と最初の実行
`Usage.md`：CSVの書き方と使い方
`FAQ.md`：困ったときのQ&A
`_Sidebar.md`：全ページに表示されるサイドバー

`_Sidebar.md` と `_Footer.md` は特別なファイル名で、置いておくとサイドバーとフッターとして表示されます（公式ドキュメントで確認）。

ページ同士のリンクは `[Setup]]` のように、二重の角かっこでページ名を囲む書き方を使いました。Markdownの通常のリンク `[表示名` でも書けます。

たとえば、トップページ（`Home.md`）の下書きはこれくらいの短さです。


# sample-tool wiki
CSVの金額をカテゴリ別に合計するツールです。
- はじめての方: [[Setup]]
- 使い方: [[Usage]]
- 困ったとき: [[FAQ]]

Claude Codeに貼ったプロンプト

実際に使った内容をもとに、読者の方がそのまま使えるように整えたプロンプトがこちらです。ターミナルで対象リポジトリのフォルダに `cd` してからClaude Codeを起動し、チャット欄に貼ってください（別の場所で起動すると、読むコードや保存先が変わってしまいます）。


このリポジトリのGitHub wikiの下書きを作ってください。

目的: 初めて使う人が、準備から実行、困ったときの対処までたどれるようにしたい
対象: このフォルダのコードとREADMEを読んで内容を把握してください
出力先: 新しく作る wiki-draft フォルダに、Home.md / Setup.md / Usage.md / FAQ.md / _Sidebar.md を作成
ページ間リンク: [[ページ名]] 形式で書いてください

書く前に、ページ構成案と各ページの見出しを先に見せてください。
コードから確認できないことは書かず、「要確認」と書いてください。
既存のファイルを上書き・削除する場合は、実行前に対象ファイル一覧と差分を表示し、私が確認してから実行してください。
不明点は推測せず、確認事項として列挙してください。

ポイントは「コードから確認できないことは書かない」と伝えることです。AIは、それらしい説明を補ってしまうことがあります。wikiは後から読む人が信じる情報なので、ここは特に気をつけたいところです。

下書きを確かめる方法：リンク切れとエッジケース

下書きができたら、2つの確認をしました。

1. リンク切れのチェック

ページが増えると、存在しないページへのリンクが紛れ込みがちです。今回は試しに、サイドバーへわざと存在しないページへのリンクを1つ入れ、次のように確認しました。


wiki-draft フォルダ内の [[ページ名]] 形式のリンクを一覧にして、
対応する .md ファイルが存在しないリンクを報告してください。
ファイルの修正はせず、報告だけしてください。

私の環境では、その1件をきちんと検出できました。

2. 書いてある手順を実際に試す

wikiに書く内容は、実際にツールを動かして確かめながら決めました。ここで気づいたのが、ツール自体の弱点です。

金額を `1,200` のようにカンマ付きで書くと、エラーにならずに「1」として集計された
`category` 列がないCSVでは、`KeyError` というエラーで止まった
金額欄に文字が入っていると、`ValueError` というエラーで止まった

1つ目は、CSVに `food,1,200` と引用符なしで書いた場合です。カンマが区切りと解釈され、「1」と「200」が別の列に分かれました。`”1,200″` と囲むと、今度は `ValueError` で止まります。エラーが出ないのに数字がおかしい、気づきにくい失敗なので、UsageとFAQに注意書きを入れました。

一方、3つ目は下書き後に試し直して見つけたもので、まだFAQに書けていません。次に追記する予定です。

ドキュメントを書くことは、ツールを見直すことでもある。これは今回いちばんの発見でした。

GitHubに反映するときの流れと注意点

GitHubのwikiに反映する流れは、公式ドキュメントによると次のとおりです（私はまだ試せていません）。

1. GitHubのリポジトリ画面で「Wiki」タブを開き、最初のページを1つ作る

2. wikiを手元にクローンする

3. 下書きのファイルをコピーして、コミット・pushする

クローンは、リポジトリのURLの末尾を `.wiki.git` にしたものを使います。


git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.wiki.git
cd YOUR-REPOSITORY.wiki

`YOUR-USERNAME` と `YOUR-REPOSITORY` は、ご自分のものに置き換えてください。公式ドキュメントでは、読者に表示されるのはデフォルトブランチにpushした内容だけとされています。

Gitに不安がある場合は、GitHubのwiki画面でページを作って本文を貼り付ける方法でも反映できます。

コピーやpushは、wikiの既存ページを上書きする可能性がある操作です。Claude Codeに頼む場合は、たとえば次のように確認を挟んでもらうと安心です（GitとGitHubへのログイン設定が済んでいる前提です）。


wiki-draft フォルダの下書きを、クローンしたwikiのフォルダに反映したいです。
コピーする前に、コピー元・コピー先と、上書きされるファイルの一覧と差分を表示してください。私が確認してから実行してください。
コミット・pushの前にも、送信先・ブランチ・変更内容を表示し、私の確認を待ってください。
不明点は推測せず、確認事項として列挙してください。

反映したら、Homeから各ページへ移動できるか、サイドバーが表示されるかをブラウザで確かめましょう。

また、ページ名（ファイル名）には `\ / : * ? ” < > |` の記号を使わないよう、公式ドキュメントで案内されています。

また、公式ドキュメントによると、wikiが検索エンジンにインデックスされるのは、スターが500以上あり、公開編集を制限しているwikiだけです。検索で見つけてもらいたい情報なら、GitHub Pagesなど別の手段も検討したほうがよさそうです。

READMEとwikiはどう使い分ける？

今のところ、READMEは「何のツールか・最短の動かし方」、wikiは「詳しい使い方やFAQなど、ページを分けたい情報」と考えています。小さなツールならREADMEだけで十分な場合も多く、どの規模からwikiを使うのが良いかは、まだわかっていません。READMEの作り方はREADMEをAIに書かせたら思ったより良かった話で紹介しています。

まとめ

GitHub wikiの書き方は、ページ構成を先に決めてからAIに下書きを頼むと進めやすい
プロンプトには「コードから確認できないことは書かない」「不明点は列挙」を入れる
リンク切れは、Claude Codeに「報告だけ」を頼むと手軽に確認できる
書いた手順を実際に試すと、ツール自体の弱点が見つかることがある
非公開リポジトリのwikiはプランによって使えない場合がある。また、公開wikiに秘密情報は書かない

ドキュメントが苦手でも、「構成を決める」「下書きを頼む」「試して直す」の3段階に分ければ、少しずつ形になります。まずは1ページ、FAQからでも始めてみてください。

GitHubそのものに慣れていない方は、GitHubを使ったことがない人がClaude Codeで始めた話やフォーク・クローンの違いを体で覚えた話もあわせてどうぞ。

なお、Gitの操作を実際に手を動かして学べる学習アプリも準備中です。app.maahsachi.com（公開準備中）で試せるようになる予定です。

参考（2026年10月時点で確認）

[About wikis（GitHub Docs）](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis)
[Adding or editing wiki pages（GitHub Docs）](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages)
[Editing wiki content（GitHub Docs）](https://docs.github.com/en/communities/documenting-your-project-with-wikis/editing-wiki-content)
[Creating a footer or sidebar for your wiki（GitHub Docs）](https://docs.github.com/en/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki)