📕 仕様書もコードと一緒に更新したい！GitHub Wikiを「使えるドキュメント」にする自動同期の仕組みを構築してみた

はじめに

開発に熱中するとついついドキュメント更新を後回しにしがちな皆さん、お元気ですか(自戒)？

「コードは最新の仕様になっているのに、ドキュメントは3ヶ月前のまま...」
「Wikiの編集画面だとレビューできないから、いつの間にか仕様が変わっていて驚く...」
「そもそもWiki使ってないし、Excel開くのはめんどいし、NotionはPMが触ってるし...」

そんな 「ドキュメント全然更新されない問題」 に終止符を打つべく、今回は

• Everything as a Code 「IaCにしたり仕様書もコードにしちゃえｯｯｯ」
• Single Source of Truth「情報は散乱させずに単一集約ｯｯｯ」

の精神に基づいたドキュメント管理システムを導入してみました。

コードと同じリポジトリで仕様書を管理し、GitHub Actionsで勝手にWikiへ同期してくれる良さげな仕組みです。
仕様書がMarkdown形式でGit管理されるため、AIが内容を解析しやすく、要約や質問応答などの活用が期待できます。

どんなものを作ったのか

どんな仕組み？

仕組みはいたってシンプルです。
リポジトリの docs/wiki/ ディレクトリ配下が「正」となるデータソースです。ここに変更がマージされると、GitHub Actionsが働き、GitHub Wiki専用のリポジトリへ内容を強制的に同期（push）します。

「ドキュメントを更新する」というタスクが、「ファイルを修正してPRを出す」という普段の開発フローに完全に統合されるのがミソです。
コードの修正ついでに「まあ、仕様書もちゃちゃっと変えとくか」ができるのが何より良い✨️

こだわりポイントと「うれしい」誤算

実際にこの運用を回してみて、想像以上に良かったポイントがいくつかあります。

1. コードとドキュメントをセットでレビューできる（これがデカい）

機能修正のPRの中に、仕様書の変更も含まれていれば、「実装と仕様のズレ」をその場で指摘できます。

GitHubのDiff画面でコードと仕様書を行き来しながらレビューできるのは、体験としてかなり良いです。「ここ実装変わったけどドキュメント直ってなくない？」が激減します。

2. Wikiが見やすいビューアーになる

リポジトリ内のMarkdownファイル（docs/wiki/*.md）を直接GitHubのファイルビューアーで探して読むのは、エンジニア以外（PMやデザイナーなど）には少しハードルが高いです。
エンジニアもレンダリングされていないMarkdownファイルを読むのは嫌ですしね。

GitHub Wikiに同期されていれば、レンダリングされた綺麗な状態かつ、おまけでサイドバーもついて誰でも閲覧できます。

不具合の修正を行う際などは、正とする仕様書がWikiにレンダリングされた状態であるので、PRにリンクを差し込んだりできます。

3. 「[private]プレフィックス」でポエムも書ける(笑)

ポエムというのは半分冗談ですが、要は DBへの接続情報や環境変数の値などの機密情報 はこの仕組みで管理できます。
「[private]」 というプレフィックスをファイル名に付けたページは同期対象外として保護されるようにしました。

「仕様書は厳格にGit管理したい」けど、「まだ仕様として固まっていない個人的なメモ」や「チーム内だけの秘密の共有事項（接続情報etc）」までPRベースで管理するのは避けたいところです。

• 仕様書: Git管理（同期される）
• 機密情報: Wikiで直接編集（同期されない・消されない）
• メモ・ポエム: Wikiで直接編集（同期されない・消されない）

この「厳格さ」と「ゆるさ」のハイブリッドな運用ができるのが、この仕組みの気に入っているところです。

「接続情報などの機密データをそもそもWikiに上げない方がいいのでは?」と考える方もいると思いますが、NotionやExcelでアクセス制御していたものがGithubのリポジトリへのアクセス制御に変わっただけだと考えています。

ただし「リポジトリをpublicに変更（めったにないと思いますが）」したり、「外部コラボレーターを招待」する際にはアクセスできてしまうので細心の注意が必要です。

導入方法

Step 1: Github Wikiの有効化 & 初期ページ作成

調べればたくさん出てくるはずですので割愛します。
※Githubの無料プランを利用されている方は、publicリポジトリでしかWikiは作ることができません。（有料プランであれば問題ないはずです）

1点だけ注意です。
有効化した後に Create the first pageと表示されると思いますので、作成しておいてください。画像2枚目の状態になっていれば問題ありません。
初期ページを作成しておかないとWorkflowでコケることになります。

Step 2: 同期用スクリプトの作成

プロジェクトのルートに scripts/sync-docs-to-wiki.js を作成し、以下のコードを貼り付けてください。依存ライブラリはありません（Node.jsの標準モジュールのみ使用）。
ちなみに私はNext.jsのプロジェクト内に配置して利用しています。

scripts/sync-docs-to-wiki.js（クリックで展開）

#!/usr/bin/env node

/**
 * docs/ 配下の設計書を GitHub Wiki に同期するスクリプト
 * 
 * このスクリプトはGitHub Actions環境でのみ実行可能です。
 * ローカル環境からの実行は許可されていません。
 */

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

// 環境変数の取得
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
const GITHUB_REPO = process.env.GITHUB_REPO || process.env.GITHUB_REPOSITORY;
const GITHUB_ACTIONS = process.env.GITHUB_ACTIONS === 'true';

// GitHub Actions環境でのみ実行を許可
if (!GITHUB_ACTIONS) {
  console.error('❌ このスクリプトはGitHub Actions環境でのみ実行できます');
  console.error('   ローカル環境からの実行は許可されていません');
  console.error('   Wiki同期はGitHub Actionsから自動的に実行されます');
  process.exit(1);
}

if (!GITHUB_TOKEN) {
  console.error('❌ GITHUB_TOKEN 環境変数が設定されていません');
  process.exit(1);
}

if (!GITHUB_REPO) {
  console.error('❌ GITHUB_REPO 環境変数が設定されていません');
  console.error('   例: GITHUB_REPO=owner/repo');
  process.exit(1);
}

const [owner, repo] = GITHUB_REPO.split('/');
if (!owner || !repo) {
  console.error('❌ GITHUB_REPO の形式が正しくありません');
  console.error('   例: GITHUB_REPO=owner/repo');
  process.exit(1);
}

// ここは実際の構成に合わせて変更してください
const DOCS_DIR = path.join(process.cwd(), 'docs', 'wiki');

// Wiki にのみ残すべきページ（削除対象外）
// [private] で始まるページは自動的に保護されます
const PROTECTED_WIKI_PAGES = [];

/**
 * docs/wiki/ 配下の Markdown ファイルを再帰的に取得
 */
function getMarkdownFiles(dir, basePath = '') {
  const files = [];
  const entries = fs.readdirSync(dir, { withFileTypes: true });

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    const relativePath = path.join(basePath, entry.name);

    if (entry.isDirectory()) {
      // サブディレクトリも含める
      files.push(...getMarkdownFiles(fullPath, relativePath));
    } else if (entry.isFile() && entry.name.endsWith('.md')) {
      files.push({
        filePath: fullPath,
        relativePath: relativePath,
        wikiTitle: getWikiTitle(relativePath),
      });
    }
  }

  return files;
}

/**
 * ファイルパスから Wiki ページタイトルを生成
 */
function getWikiTitle(relativePath) {
  // ファイル名から拡張子を除去
  const nameWithoutExt = relativePath.replace(/\.md$/, '');
  
  // パス区切りをハイフンに変換（必要に応じて調整）
  // 例: "01_要件定義書" -> "01_要件定義書"
  // 例: "01_要件定義書/顧客要件" -> "01_要件定義書-顧客要件"
  return nameWithoutExt.replace(/\//g, '-');
}

/**
 * Wiki ページを作成または更新（Gitリポジトリ経由）
 */
function createOrUpdateWikiPage(title, content, wikiDir) {
  const fileName = `${title}.md`;
  const filePath = path.join(wikiDir, fileName);

  // ファイルが既に存在するか確認
  const exists = fs.existsSync(filePath);
  
  // ファイルを書き込み
  fs.writeFileSync(filePath, content, 'utf-8');
  
  // Gitに追加
  execSync(`cd "${wikiDir}" && git add "${fileName}"`, { stdio: 'pipe' });
  
  if (exists) {
    console.log(`✅ 更新: ${title}`);
  } else {
    console.log(`✨ 作成: ${title}`);
  }
}

/**
 * Wiki リポジトリからすべてのページを取得（Git操作のみ）
 */
function getAllWikiPages(wikiDir) {
  const pages = [];
  
  if (!fs.existsSync(wikiDir)) {
    return [];
  }

  const files = fs.readdirSync(wikiDir);
  for (const file of files) {
    if (file.endsWith('.md')) {
      const title = file.replace(/\.md$/, '');
      // システムページは除外
      if (title !== '_Sidebar' && title !== 'Home') {
        pages.push({
          title: title,
          fileName: file,
        });
      }
    }
  }

  return pages;
}

/**
 * ページタイトルが保護対象かどうかを判定
 */
function isProtectedPage(title) {
  // [private] で始まるページは保護対象
  if (title.startsWith('[private]')) {
    return true;
  }
  
  // 明示的に指定された保護対象ページ
  return PROTECTED_WIKI_PAGES.some(protectedPage => {
    // 完全一致または、スラッシュ/ハイフンの違いを考慮
    return title === protectedPage || 
           title === protectedPage.replace(/\//g, '-') ||
           title === protectedPage.replace(/-/g, '/');
  });
}

/**
 * Wiki ページを削除（Git操作のみ）
 */
function deleteWikiPages(wikiDir, pagesToDelete) {
  if (pagesToDelete.length === 0) {
    return 0;
  }

  let deletedCount = 0;
  for (const pageTitle of pagesToDelete) {
    const fileName = `${pageTitle}.md`;
    const filePath = path.join(wikiDir, fileName);
    
    if (fs.existsSync(filePath)) {
      execSync(`cd "${wikiDir}" && git rm "${fileName}"`, { stdio: 'pipe' });
      console.log(`🗑️  削除: ${pageTitle}`);
      deletedCount++;
    }
  }

  return deletedCount;
}

/**
 * メイン処理
 */
function main() {
  console.log(`📚 ${GITHUB_REPO} の Wiki に同期を開始します...\n`);

  // docs/wiki/ ディレクトリの存在確認
  if (!fs.existsSync(DOCS_DIR)) {
    console.error(`❌ docs/wiki/ ディレクトリが見つかりません: ${DOCS_DIR}`);
    process.exit(1);
  }

  // Markdown ファイルの取得
  const files = getMarkdownFiles(DOCS_DIR);
  console.log(`📄 ${files.length} 個の Markdown ファイルが見つかりました\n`);

  // Wikiリポジトリをクローン
  const wikiDir = path.join(process.cwd(), '.wiki-temp');
  // GitHub Actions環境では、URLに直接トークンを埋め込む（ユーザー名に x-access-token を利用）
  const encodedToken = encodeURIComponent(GITHUB_TOKEN);
  const wikiRepoUrl = `https://x-access-token:${encodedToken}@github.com/${owner}/${repo}.wiki.git`;
  const gitUserName = process.env.GITHUB_ACTOR || 'github-actions[bot]';
  const gitUserEmail = process.env.GIT_COMMIT_EMAIL || `${gitUserName}@users.noreply.github.com`;
 
  try {
    // GitHub Actions環境でのGit認証設定
    // GIT_TERMINAL_PROMPTを0に設定してパスワードプロンプトを無効化
    const gitEnv = {
      ...process.env,
      GIT_TERMINAL_PROMPT: '0',
      GIT_ASKPASS: 'echo',
    };
 
    if (!fs.existsSync(wikiDir)) {
      console.log('📥 Wiki リポジトリをクローン中...\n');
      execSync(`git clone "${wikiRepoUrl}" "${wikiDir}"`, { 
        stdio: 'inherit',
        env: gitEnv
      });
    } else {
      execSync(`cd "${wikiDir}" && git pull origin master`, { 
        stdio: 'pipe',
        env: gitEnv
      });
    }
 
    // リモートURLを認証付きURLに更新（既存クローン対策）
    execSync(`cd "${wikiDir}" && git remote set-url origin "${wikiRepoUrl}"`, {
      stdio: 'pipe',
      env: gitEnv,
    });

    // Gitユーザー情報を設定
    execSync(`cd "${wikiDir}" && git config user.name "${gitUserName}"`, {
      stdio: 'pipe',
      env: gitEnv,
    });
    execSync(`cd "${wikiDir}" && git config user.email "${gitUserEmail}"`, {
      stdio: 'pipe',
      env: gitEnv,
    });

    // Wiki リポジトリから既存のページを取得
    const wikiPages = getAllWikiPages(wikiDir);
    const docsWikiTitles = new Set(files.map(f => f.wikiTitle));
    
    // 保護対象ページを取得（サイドバーに含めるため）
    const protectedPages = wikiPages
      .filter(page => {
        const title = page.title;
        return isProtectedPage(title);
      })
      .map(page => ({
        title: page.title,
        wikiTitle: page.title,
        fileName: page.fileName,
      }));

    // すべてのファイルを追加
    for (const file of files) {
      const content = fs.readFileSync(file.filePath, 'utf-8');
      createOrUpdateWikiPage(file.wikiTitle, content, wikiDir);
    }

    // サイドバーを作成
    const sidebarContent = `# 目次

${files
  .filter(f => !f.relativePath?.includes('wiki-backup'))
  .map(f => `- [[${f.wikiTitle}|${f.wikiTitle}]]`)
  .join('\n')}

${protectedPages.length > 0 ? `## Wiki 専用ページ\n\n${protectedPages.map(p => `- [[${p.wikiTitle}|${p.wikiTitle}]]`).join('\n')}\n` : ''}
`;
    createOrUpdateWikiPage('_Sidebar', sidebarContent, wikiDir);

    // 削除対象のページを処理
    const pagesToDelete = wikiPages
      .filter(page => {
        const title = page.title;
        // 保護対象ページは削除しない
        if (isProtectedPage(title)) {
          return false;
        }
        // docs/wiki/ に存在しないページのみ削除対象
        return !docsWikiTitles.has(title);
      })
      .map(page => page.title);

    // 保護対象ページの確認ログ
    const allProtectedPages = wikiPages.filter(page => isProtectedPage(page.title));
    if (allProtectedPages.length > 0) {
      console.log(`\n🔒 保護された Wiki ページ（削除対象外）: ${allProtectedPages.length} 個`);
      allProtectedPages.forEach(page => console.log(`   - ${page.title}`));
    }

    if (pagesToDelete.length > 0) {
      console.log(`\n🗑️  削除対象の Wiki ページ: ${pagesToDelete.length} 個`);
      pagesToDelete.forEach(title => console.log(`   - ${title}`));
      deleteWikiPages(wikiDir, pagesToDelete);
    } else {
      console.log('\n✅ 削除対象のページはありませんでした');
    }

    // 変更があるか確認してコミット・プッシュ
    try {
      execSync(`cd "${wikiDir}" && git diff --cached --quiet`, { stdio: 'pipe' });
      console.log('\n✅ 変更はありませんでした');
    } catch {
      // 変更がある場合はコミット・プッシュ
      console.log('\n💾 変更をコミット中...');
      execSync(`cd "${wikiDir}" && git commit -m "Sync docs/wiki to GitHub Wiki"`, { stdio: 'inherit' });
      
      console.log('📤 変更をプッシュ中...');
      execSync(`cd "${wikiDir}" && git push origin master`, { 
        stdio: 'inherit',
        env: gitEnv
      });
      
      console.log('\n✅ Wikiへの同期が完了しました！');
    }
  } finally {
    // 一時ディレクトリをクリーンアップ
    if (fs.existsSync(wikiDir)) {
      execSync(`rm -rf "${wikiDir}"`, { stdio: 'pipe' });
    }
  }
}

try {
  main();
} catch (error) {
  console.error('\n❌ エラーが発生しました:', error);
  process.exit(1);
}

Step 3: GitHub Actionsのワークフロー作成

.github/workflows/sync-wiki.yml を作成します。
これもまた特別な依存関係は不要で、標準的な Node.js 環境があれば動作します。

name: Sync Docs to Wiki

on:
  push:
    branches:
      - main
      - develop
    paths:
      - 'docs/wiki/**/*.md'
  workflow_dispatch: # 手動実行も可能

jobs:
  sync-wiki:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"

      - name: Sync docs to Wiki
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_REPO: ${{ github.repository }}
        run: node scripts/sync-docs-to-wiki.js

Step 4: サンプルファイルを追加して実行してみる

サンプルとしてこんな階層のファイルを追加してみます。

docs/wiki/
├── Home.md
├── 01_要件定義書/
│   ├── 開発要件.md
│   └── 顧客要件.md
└── 02_権限設計書/
    ├── 一般ユーザー.md
    └── 管理者ユーザー.md

参考までに、私はHome.mdにこのような記載を入れて理解を促しています。

docs/wiki/Home.md（クリックで展開）

# Wiki の概要

この Wiki はソースコード側リポジトリ内の `docs/wiki` ディレクトリにある Markdown ファイルと同期されています。

- 同期対象: `docs/wiki` 配下の `.md` ファイル
- 除外対象: ファイル名（ページタイトル）が `[private]` で始まるページは同期されません

設計書や各種ドキュメントの更新は `docs/wiki` 配下で行い、`main` または `develop` ブランチに変更をプッシュすることで自動的に Wiki へ反映されます。

> [!WARNING]
> Wiki 上で直接編集した内容は次の同期で上書きされます。必ずリポジトリの `docs/wiki` 配下で編集してください。

> [!IMPORTANT]
> 秘匿情報など Wiki のみで保持したい内容がある場合は、ページタイトルを `[private]` で始めてコンソール上から編集してください（同期対象外になります）。

実装の裏側（開発者向け）

同期処理の心臓部は scripts/sync-docs-to-wiki.js というNode.jsスクリプトです。
ただファイルをコピーするだけでなく、開発体験を損なわないための「気の利いた処理😎」をいくつか入れています。

ディレクトリ階層をフラットに変換

リポジトリ内では整理のためにディレクトリを分けたいですが、GitHub Wikiはフラットな構造しか持ちません。そこで、ファイルパスのスラッシュをハイフンに置換して、一意なタイトルを生成しています。

function getWikiTitle(relativePath) {
  // 例: "akfm-knowledge/part_1.md" -> "akfm-knowledge-part_1"
  const nameWithoutExt = relativePath.replace(/\.md$/, '');
  return nameWithoutExt.replace(/\//g, '-');
}

サイドバーの自動生成

Wikiのサイドバー（_Sidebar）を手動で更新するのは面倒すぎます（絶対更新忘れるやつ）。
だからこそ、ファイル一覧から勝手に作ってもらうようにしました。

// scripts/sync-docs-to-wiki.js より抜粋（雰囲気）
const sidebarContent = `# 目次

${files
  .map(f => `- [[${f.wikiTitle}|${f.wikiTitle}]]`)
  .join('\n')}

${protectedPages.length > 0 ? `## Wiki 専用ページ\n\n${protectedPages.map(p => `- [[${p.wikiTitle}|${p.wikiTitle}]]`).join('\n')}\n` : ''}
`;

これで、ファイルを追加するだけでWikiの目次も更新されます。最高。

「[private]」ページの保護ロジック

前述した「ポエム保護機能(笑)」の実装です。
同期スクリプトは基本的に「リポジトリにないWikiページはゴミとみなして削除する」という挙動をしますが、このプレフィックスがある場合だけは特別扱いして削除をスキップします。

function isProtectedPage(title) {
  // [private] で始まるページは保護対象
  if (title.startsWith('[private]')) {
    return true;
  }
  return false;
}

// 削除処理の中で...
const pagesToDelete = wikiPages.filter(page => {
    // 保護対象なら削除リストに入れない！
    if (isProtectedPage(page.title)) return false;
    // リポジトリに存在しないなら削除
    return !docsWikiTitles.has(page.title);
});

参考までに（Github）

https://github.com/ShoWaka/sync-docs-to-wiki

まとめ

ドキュメント管理は「継続できること」と「最新版が特定できること」が一番大事だと思っています。
とりあえずこの仕組みを導入して、チーム内でドキュメント管理にトライしています。
Claude CodeのHooksでやって貰う方法もあるのかなーなんて思ってたりしています。

機密情報の取り扱いには十分ご注意くださいませ。