Development Setup and Testing

Development-Setup-and-Testing

wikigen の開発環境セットアップ、プロジェクト構成、コードレビュー自動化、および Claude Code スキルファイル統合について説明するページです。wikigen は外部依存ライブラリを持たない純粋な Go 標準ライブラリのみで実装されているため、開発環境の構築は最小限の手順で完了します。本ページは Build & Deployment および GitHub Actions Integration と密接に関連しています。

前提条件

wikigen を開発・実行するために必要なツールは以下の 3 つです。

ツール	最低バージョン	用途
Go	1.22+	バイナリのビルドおよび実行
git	任意の安定版	リポジトリのクローンおよびバージョン管理
Claude CLI (`claude`)	最新版	Wiki ページのコンテンツ生成

Sources: .repos/tomohiro-owada_wikigen/go.mod:1-3、.repos/tomohiro-owada_wikigen/.github/workflows/wiki.yml:22-35

Go のインストール確認

go version
# go version go1.22.x linux/amd64

Claude CLI のインストール

Claude CLI は npm 経由でインストールします。GitHub Actions ワークフローでも同様の手順が使用されています。

npm install -g @anthropic-ai/claude-code

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/wiki.yml:34-35

インストール後、Claude CLI の認証を完了させる必要があります。wikigen の起動時に claude コマンドが見つからない場合、以下のエラーが出力されて終了します。

if _, err := exec.LookPath(claudePath); err != nil {
    fmt.Fprintf(os.Stderr, "Error: claude CLI not found. Install from https://claude.ai/claude-code\n")
    os.Exit(1)
}

Sources: .repos/tomohiro-owada_wikigen/main.go:934-937

プロジェクト構成

wikigen/
├── main.go               # 全ロジックを含む単一ソースファイル (1068行)
├── go.mod                # Go モジュール定義 (依存ライブラリなし)
├── repos.txt             # バッチ処理用リポジトリリストのサンプル
├── .env.example          # 環境変数設定のテンプレート
├── .gitignore            # .env, wikigen バイナリ, wiki-output/, .repos/ を除外
├── README.md             # 日英バイリンガルのドキュメント
├── article.md            # 設計思想に関する技術記事
├── .github/
│   └── workflows/
│       ├── wiki.yml      # Wiki 自動生成ワークフロー
│       ├── claude.yml    # Claude Code コードレビューワークフロー
│       └── release.yml   # マルチプラットフォームリリースワークフロー
└── .claude/
    └── skills/
        └── wikigen/
            └── SKILL.md  # Claude Code スキルファイル

Sources: .repos/tomohiro-owada_wikigen/main.go、.repos/tomohiro-owada_wikigen/.github/workflows/、.repos/tomohiro-owada_wikigen/.claude/skills/wikigen/SKILL.md

go.mod の内容

wikigen は外部パッケージへの依存を持たず、Go 標準ライブラリのみで実装されています。

module wikigen

go 1.25.7

Sources: .repos/tomohiro-owada_wikigen/go.mod:1-3

ビルド手順

flowchart TD
    A[ソースコード取得] --> B[go build 実行]
    B --> C[wikigen バイナリ生成]
    C --> D[.env ファイル設定]
    D --> E[動作確認: dry-run]
    E --> F[Wiki 生成]

バイナリのビルド

Makefile は存在しないため、go build コマンドを直接使用します。

# リポジトリをクローン
git clone https://github.com/tomohiro-owada/wikigen.git
cd wikigen

# バイナリをビルド
go build -o wikigen .

# 動作確認 (dry-run モード)
./wikigen -dry-run owner/repo

Sources: .repos/tomohiro-owada_wikigen/.claude/skills/wikigen/SKILL.md:15-29

環境変数の設定

.env.example をコピーして .env ファイルを作成し、必要な値を設定します。.gitignore により .env はバージョン管理から除外されます。

cp .env.example .env

設定可能なパラメータ

環境変数	デフォルト値	説明
`GITHUB_TOKEN`	(空: SSH使用)	GitHub Personal Access Token
`CLAUDE_MODEL`	(空: デフォルトモデル)	Claude モデル (haiku / sonnet / opus)
`WIKI_LANGUAGE`	`ja`	出力言語コード
`WIKI_PARALLEL`	`1`	リポジトリ並列処理数
`WIKI_PAGE_PARALLEL`	`3`	ページ並列処理数
`WIKI_OUTPUT_DIR`	`./wiki-output`	出力ディレクトリ
`WIKI_CLONE_DIR`	`./.repos`	クローン先ディレクトリ

Sources: .repos/tomohiro-owada_wikigen/.env.example:1-21

.env ファイルの記述例:

# GitHub Personal Access Token (optional — if empty, SSH is used)
# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Claude model (optional: haiku, sonnet, opus)
# CLAUDE_MODEL=haiku

# Output language (default: ja)
# WIKI_LANGUAGE=ja

Sources: .repos/tomohiro-owada_wikigen/.env.example:1-8

開発時のフラグ

main.go の flag.Parse() 処理では、環境変数よりもコマンドライン引数が優先されます。

flag.StringVar(&token, "token", os.Getenv("GITHUB_TOKEN"), "GitHub PAT (default: $GITHUB_TOKEN, empty=SSH)")
flag.StringVar(&model, "model", envOrDefault("CLAUDE_MODEL", ""), "claude model (e.g., haiku, sonnet, opus)")
flag.StringVar(&language, "lang", envOrDefault("WIKI_LANGUAGE", "ja"), "output language")
flag.StringVar(&outputDir, "o", envOrDefault("WIKI_OUTPUT_DIR", "./wiki-output"), "output directory")
flag.StringVar(&cloneDir, "clone-dir", envOrDefault("WIKI_CLONE_DIR", "./.repos"), "clone directory")
flag.IntVar(&parallel, "p", envOrDefaultInt("WIKI_PARALLEL", 1), "parallel projects/repos")
flag.IntVar(&pageParallel, "pp", envOrDefaultInt("WIKI_PAGE_PARALLEL", 3), "parallel pages per project")

Sources: .repos/tomohiro-owada_wikigen/main.go:906-913

開発時の推奨フラグ

フラグ	目的
`-dry-run`	ページ構造のみを確認。API 呼び出しコストを抑えて構成を検証
`-pp 1`	ページ生成を逐次実行。デバッグ時にログを読みやすくする
`-model haiku`	軽量モデルを使用して開発・テスト時のコストを削減
`-json`	構造化 JSON 出力。スクリプトやツールとの連携に利用
`-log /tmp/wikigen.log`	ログをファイルに出力して詳細なデバッグを実施

テスト戦略

wikigen にはユニットテストファイル (*_test.go) が存在しません。その代わり、以下の方法で品質を確保しています。

flowchart TD
    A[コード変更] --> B[dry-run で構造確認]
    B --> C{構造は正しいか}
    C -- No --> A
    C -- Yes --> D[小規模リポジトリで全生成テスト]
    D --> E[_errors.log 確認]
    E --> F{エラーあり}
    F -- Yes --> G[-retry フラグで再生成]
    G --> E
    F -- No --> H[JSON 出力で結果検証]
    H --> I[完了]

手動テストの手順

1. 構造確認 (dry-run)

./wikigen -dry-run owner/repo

dry-run モードではページ生成を行わず、Wiki の構造（ページタイトルと説明一覧）のみを出力します。

2. 最小構成での生成テスト

./wikigen -model haiku -pp 1 -lang en owner/repo

3. エラーログの確認

cat wiki-output/repo/_errors.log

4. 失敗ページの再生成

./wikigen -retry

Sources: .repos/tomohiro-owada_wikigen/.claude/skills/wikigen/SKILL.md:72-77

JSON 出力による結果検証

-json フラグを使用すると、生成結果を構造化 JSON で取得できます。

./wikigen -json owner/repo | jq '.pages[] | select(.status == "failed")'

詳細は JSON Output & Structured Results を参照してください。

Claude Code スキルファイルの統合

wikigen は .claude/skills/wikigen/SKILL.md に Claude Code スキルファイルを含んでいます。このファイルにより、Claude Code が wikigen ツールの使い方を理解してユーザーを支援できます。

SKILL.md の構成

---
name: wikigen
description: Generate GitHub Wiki documentation from source code repositories.
argument-hint: "[owner/repo or repos.txt path]"
disable-model-invocation: true
allowed-tools: Bash(./wikigen *), Read, Glob
---

Sources: .repos/tomohiro-owada_wikigen/.claude/skills/wikigen/SKILL.md:1-7

主要な設定項目

設定	値	説明
`disable-model-invocation`	`true`	Claude がスキル独自の LLM 呼び出しを行わない
`allowed-tools`	`Bash(./wikigen *)`, `Read`, `Glob`	許可するツール操作を限定
`argument-hint`	`[owner/repo or repos.txt path]`	引数のヒント表示

disable-model-invocation: true は、Claude Code がスキルを起動する際に独立したモデル呼び出しを行わず、wikigen バイナリそのものを実行することを示します。

Sources: .repos/tomohiro-owada_wikigen/.claude/skills/wikigen/SKILL.md:5-6

Claude Code によるコードレビュー自動化

wikigen プロジェクトは、GitHub Actions を通じて Claude Code による自動コードレビューを導入しています。

claude.yml ワークフロー

name: Claude Code

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/claude.yml:1-12

トリガー条件

Claude Code アクションは、コメントやレビュー本文に @claude が含まれる場合にのみ実行されます。

if: |
  (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
  (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
  (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
  (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/claude.yml:15-19

必要な権限と認証

権限	用途
`contents: read`	リポジトリコードの読み取り
`pull-requests: read`	PR 情報の読み取り
`issues: read`	Issue 情報の読み取り
`id-token: write`	OIDC 認証
`actions: read`	CI 結果の読み取り

認証には CLAUDE_CODE_OAUTH_TOKEN シークレットが必要です。

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/claude.yml:21-37

コードレビューの動作フロー

sequenceDiagram
    participant Dev as 開発者
    participant GH as GitHub
    participant Actions as GitHub Actions
    participant Claude as Claude Code

    Dev->>GH: PR/Issue にコメント (@claude)
    GH->>Actions: Webhook イベント送信
    Actions->>Actions: @claude メンション確認
    Actions->>Claude: claude-code-action@v1 実行
    Claude->>GH: リポジトリコード取得
    Claude->>GH: CI 結果取得 (actions: read)
    Claude->>GH: コメントで応答
    GH->>Dev: 通知

Wiki 自動生成ワークフロー

ソースコードが変更された際に Wiki を自動生成するワークフローも整備されています。

wiki.yml のトリガー条件

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - '*.go'
      - 'go.mod'
      - 'go.sum'

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/wiki.yml:3-10

Go ソースファイルまたはモジュールファイルが変更された場合にのみ実行されます。

ワークフローの実行ステップ

flowchart TD
    A[Push to main / workflow_dispatch] --> B[Checkout]
    B --> C[Setup Go 1.22]
    C --> D[go build -o wikigen .]
    D --> E[Setup Node.js 20]
    E --> F[npm install -g @anthropic-ai/claude-code]
    F --> G[wikigen -lang en -pp 3 -model haiku]
    G --> H[wikigen -retry]
    H --> I[git clone wiki-repo]
    I --> J{変更あり?}
    J -- Yes --> K[git commit & push]
    J -- No --> L[No wiki changes]

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/wiki.yml:26-67

実行コマンド

# Wiki 生成
./wikigen -lang en -pp 3 -model haiku -token "${{ secrets.GITHUB_TOKEN }}" tomohiro-owada/wikigen

# 失敗ページの再生成 (always 条件で必ず実行)
./wikigen -retry

Sources: .repos/tomohiro-owada_wikigen/.github/workflows/wiki.yml:40-46

開発ワークフロー全体像

flowchart TD
    A[コード変更] --> B[ローカルでビルド]
    B --> C[dry-run テスト]
    C --> D[PR 作成]
    D --> E[Claude Code レビュー]
    E --> F{承認?}
    F -- No --> A
    F -- Yes --> G[main にマージ]
    G --> H[wiki.yml 自動トリガー]
    H --> I[wikigen バイナリビルド]
    I --> J[Claude CLI インストール]
    J --> K[Wiki 生成]
    K --> L[失敗ページ再生成]
    L --> M[Wiki リポジトリへ Push]

依存関係の管理

wikigen は Go 標準ライブラリのみを使用しており、外部パッケージへの依存がありません。そのため go.sum ファイルは存在せず、go mod tidy の実行も不要です。

module wikigen

go 1.25.7

実行時に依存するシステムコマンドは以下の 2 つです。

コマンド	用途	確認方法
`git`	リポジトリのクローンとプル操作	`git --version`
`claude`	Wiki コンテンツの生成	`claude --version`

Sources: .repos/tomohiro-owada_wikigen/main.go:934

Development Setup and Testing

Development-Setup-and-Testing

前提条件

Go のインストール確認

Claude CLI のインストール

プロジェクト構成

go.mod の内容

ビルド手順

バイナリのビルド

環境変数の設定

設定可能なパラメータ

開発時のフラグ

開発時の推奨フラグ

テスト戦略

手動テストの手順

1. 構造確認 (dry-run)

2. 最小構成での生成テスト

3. エラーログの確認

4. 失敗ページの再生成

JSON 出力による結果検証

Claude Code スキルファイルの統合

SKILL.md の構成

主要な設定項目

Claude Code によるコードレビュー自動化

claude.yml ワークフロー

トリガー条件

必要な権限と認証

コードレビューの動作フロー

Wiki 自動生成ワークフロー

wiki.yml のトリガー条件

ワークフローの実行ステップ

実行コマンド

開発ワークフロー全体像

依存関係の管理

関連ページ

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!