code-wiki

Code Wiki スキル

あらゆるコードベースの完全な Wiki を生成します。概要、アーキテクチャ、モジュールごとの詳細解説、Mermaid のクラス図とシーケンス図を作成します。Google CodeWiki に着想を得ていますが、ローカルリポジトリ、プライベートリポジトリ、あらゆる言語に対応します。既存の Hermes ツール（terminal、read_file、search_files、write_file）のみを使用し、Docker、外部サービス、追加の依存関係は不要です。

このスキルが作成するのはリファレンスドキュメント（何をするか、どう動くか）です。戦略的な説明（なぜ存在するのか）は作成しません。それは別のスキルの役割です。

使用するタイミング

• ユーザーが「このコードベースのドキュメントを作成して」「Wiki を生成して」「アーキテクチャ図を作って」と依頼したとき
• 不慣れなリポジトリへのオンボーディングに、構成されたリファレンスを求めているとき
• ユーザーが GitHub URL を示し、ドキュメントの作成を依頼したとき
• GitHub 上でレンダリングできる、安定した成果物（Markdown と Mermaid）が必要なとき

次の場合には使用しないでください。

• 単一ファイルや単一関数のドキュメント作成：そのまま回答してください
• 特定の単一エンドポイントの API リファレンス：read_file を使い、回答に直接記載してください
• 戦略的な「これはなぜ存在するのか」という説明：目的の異なる別のスキルを使用してください
• このセッションでユーザーが開発中のコードベース：質問に応じてその都度回答してください

前提条件

• 環境変数は不要です。
• リポジトリの SHA の追跡とリモートリポジトリのクローンには、PATH 上に git が必要です。
• 言語別統計には、必要に応じて pygount を使用できます（codebase-inspection スキルを参照）。

実行方法

対象リポジトリのルートから terminal ツールを呼び出し、続いて read_file／search_files／write_file を使って Wiki を作成します。デフォルトの出力先は ~/.hermes/wikis/<repo-name>/ です。ユーザーが明示的に依頼した場合に限り、リポジトリ内（docs/wiki/）に書き込みます。

クイックリファレンス

手順	操作
1	対象を解決する — ローカルの cwd、指定されたパス、または一時ディレクトリへの git clone --depth 50 <url>
2	構造をスキャンする — ls、find -maxdepth 3、マニフェストファイル、README
3	ドキュメント化するモジュールを 8～10 個選ぶ
4	README.md（概要とモジュールマップ）を作成する
5	Mermaid フローチャートを含む architecture.md を作成する
6	modules/ にモジュールごとのドキュメントを作成する
7	diagrams/class-diagram.md（Mermaid classDiagram）を作成する
8	diagrams/sequences.md（Mermaid sequenceDiagram、ワークフロー 2～4 件）を作成する
9	getting-started.md を作成する
10	該当する場合は api.md を作成し、該当しない場合は省略する
11	.codewiki-state.json を作成する
12	ユーザーにパスを報告する

手順

1. 対象を解決する

GitHub URL の場合：

WIKI_TMP=$(mktemp -d)
git clone --depth 50 <url> "$WIKI_TMP/repo"
cd "$WIKI_TMP/repo"
REPO_SHA=$(git rev-parse HEAD)
REPO_NAME=$(basename <url> .git)

ローカルパスの場合（指定がなければ cwd）：

cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")

続いて、出力ディレクトリを設定します。

OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"

2. リポジトリの構造をスキャンする

シェル操作には terminal ツールを使い、マニフェストの読み取りには read_file を使います。

# Shallow tree first
ls -la

# Deeper tree, noise filtered
find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules*' \
  -not -path '*/venv*' \
  -not -path '*/__pycache__*' \
  -not -path '*/dist*' \
  -not -path '*/build*' \
  -not -path '*/target*' \
  -maxdepth 3 | sort

# Language breakdown (skip if pygount unavailable)
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
  . 2>/dev/null || true

続いて、関連するマニフェスト（package.json、pyproject.toml、setup.py、Cargo.toml、go.mod、pom.xml、build.gradle）とプロジェクトの README を read_file で読み取ります。ファイル名を推測するのではなく、search_files target='files' を使って見つけてください。

3. ドキュメント化するモジュールを選ぶ

最初の作業では、対象を8～10 個までに絞ります。言語別の目安：

• Python：トップレベルパッケージ（__init__.py を含むディレクトリ）とサブシステムのディレクトリ
• JS/TS：src/<subdir>、トップレベルのワークスペースディレクトリ
• Rust：ワークスペース内の各クレート、またはトップレベルの src/<module> ディレクトリ
• Go：トップレベルの各パッケージディレクトリ
• 混在した言語や不慣れな言語：ソースコードを含むトップレベルディレクトリ（設定やテストを除く）

非常に大規模なリポジトリでは、次の順に優先します。

1. インポート元の数（多くのモジュールからインポートされるモジュールは中核です）
2. LOC（規模の大きなモジュールは個別のドキュメントが必要となる傾向があります）
3. README／トップレベルのドキュメントでの言及数

大規模なリポジトリでは、モジュールごとのドキュメントを生成する前に、対象モジュールの一覧をユーザーに伝えてください。必要に応じて対象を変更できます。

4. README.md を作成する

実際のプロジェクト README と、エントリーポイントとなる上位 2～3 個のファイルを read_file で読み取ります。続いて write_file を使います。

# <Project Name>

<One paragraph: what it is and what it's for. Self-contained — don't assume the
reader has the source README.>

## Key Concepts

- **<Concept 1>** — <one line>
- **<Concept 2>** — <one line>

## Entry Points

- [`path/to/main.py`](<link>) — <what runs when you start it>
- [`path/to/cli.py`](<link>) — <CLI surface>

## High-Level Architecture

<2-3 sentences. Detail goes in architecture.md.>

See [architecture.md](architecture.md).

## Module Map

| Module | Purpose |
|---|---|
| [`<module>`](modules/<module>.md) | <one-line purpose> |

## Getting Started

See [getting-started.md](getting-started.md).

ローカルモードでは、リンク先に相対パスを使用します。クローンしたリポジトリでは、今後のコミット後もリンクが有効なように、https://github.com/<owner>/<repo>/blob/<sha>/<path> を使用します。

5. architecture.md を作成する

# Architecture

<2-3 paragraphs: shape of the system. What talks to what. Where data enters,
where it exits, where state lives.>

## Components

- **<Component>** — <1-2 sentences>. See [`modules/<module>.md`](modules/<module>.md).

## System Diagram

```mermaid
flowchart TD
    User([User]) --> Entry[Entry Point]
    Entry --> Core[Core Engine]
    Core --> StorageA[(Database)]
    Core --> ExternalAPI{{External API}}
```

## Data Flow

1. **<Step>** — [`<file>`](<link>)
2. **<Step>** — [`<file>`](<link>)

## Key Design Decisions

- <Anything load-bearing the reader should know>

Mermaid の図形の意味：

• [] = コンポーネント
• [()] = データベース／ストレージ
• {{}} = 外部サービス
• (()) = エントリーポイントまたは終端
• --> = 同期呼び出し、-.-> = 非同期／イベント

図あたりのノード数は約20個までにしてください。それを超える場合は、複数の図に分けてください。

6. modules/ にモジュールごとのドキュメントを作成する

選択した各モジュールについて、ls で構成を調べ、重要なファイルを3～5個特定します（サイズ、core.py／main.py／__init__.py という名前かどうか、インポート頻度などを基準にします）。その後、該当するファイルを read_file で読み取ります（必要な部分だけ読むために offset／limit を使い、特定のシンボルには search_files を優先してください）。

# Module: `<module>`

<1-2 sentence purpose.>

## Responsibilities

- <bullet>
- <bullet>

## Key Files

- [`<module>/<file>`](<link>) — <what it does>

## Public API

<Functions/classes/constants other code uses. Group related items. Show
signatures, not full implementations.>

## Internal Structure

<How the module is organized internally. State management.>

## Dependencies

- **Used by:** <other modules>
- **Uses:** <other modules + external libs>

## Notable Patterns / Gotchas

- <Anything non-obvious>

7. diagrams/class-diagram.md を作成する

最も重要なクラス／型を5～10個選びます。それらを read_file で読み取ってから、次のように作成します。

# Class Diagram

## Core Types

```mermaid
classDiagram
    class Agent {
        +string name
        +list~Tool~ tools
        +chat(message) string
    }
    class Tool {
        <<interface>>
        +name string
        +execute(args) any
    }
    Agent --> Tool : uses
    Tool <|-- TerminalTool
    Tool <|-- WebTool
```

## Notes

<Anything the diagram can't express — lifecycle, threading, etc.>

クラスのない言語（Go、C、Rust）では、構造体の関係を図にするか、class-diagram.md を省略して architecture.md の文章で説明してください。無理に当てはめないでください。

8. diagrams/sequences.md を作成する

最も重要なワークフローを2～4個選びます。コード内の呼び出し経路を追跡し（エントリーポイントを読み、関数呼び出しをたどります）、次のように作成します。

# Sequence Diagrams

## Workflow: <Name>

<1 sentence describing what this does and when it runs.>

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Agent
    participant LLM
    User->>CLI: types message
    CLI->>Agent: chat(message)
    Agent->>LLM: API call
    LLM-->>Agent: response + tool_calls
    Agent->>Agent: execute tools
    Agent-->>CLI: final response
```

### Walkthrough

1. **User input** — [`cli.py:HermesCLI.run_session`](<link>)
2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<link>)

参加者をでっち上げないでください。各ボックスは、読者がコード内で確認できる実際のコンポーネントに対応している必要があります。

9. getting-started.md を作成する

# Getting Started

## Prerequisites

<From manifest files + README. Be specific — versions if pinned.>

## Installation

```bash
<exact commands>
```

## First Run

```bash
<minimum command to see the system do something useful>
```

## Common Workflows

### <Workflow 1>
<commands>

## Configuration

- `<config-file>` — <what it controls>
- Env var `<VAR>` — <what it controls>

## Where to Go Next

- Architecture: [architecture.md](architecture.md)
- Module reference: [README.md#module-map](README.md#module-map)

10. api.md を作成する（該当しない場合は省略）

プロジェクトがライブラリまたは API サーバーの場合にのみ作成してください。該当する場合は、次の手順を実行します。

• 公開 API の範囲を特定する（__init__.py のエクスポート、OpenAPI 仕様、ルートハンドラー、エクスポートされた型）
• 公開エントリーごとに、シグネチャー、パラメーター、戻り値の型、1行の説明を記載する
• カテゴリーごとにグループ化する

11. 状態ファイルを作成する

cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF
{
  "repo_name": "$REPO_NAME",
  "source_path": "$PWD",
  "source_sha": "$REPO_SHA",
  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "generator": "hermes-agent code-wiki skill v0.1.0",
  "modules_documented": []
}
EOF

12. ユーザーに報告する

生成した内容とその保存先を正確に伝えてください。

Generated wiki at ~/.hermes/wikis/<repo-name>/:
  README.md                   project overview, module map
  architecture.md             system architecture + flowchart
  getting-started.md          setup, first run, workflows
  modules/<N files>           per-module deep-dives
  diagrams/architecture.md    Mermaid flowchart
  diagrams/class-diagram.md   Mermaid class diagram
  diagrams/sequences.md       Mermaid sequence diagrams

一時ディレクトリにクローンした場合は、ユーザーが Wiki を確認した後に削除できることを伝えてください（rm -rf "$WIKI_TMP"）。

対象範囲の制御

50万行のコードからなるモノレポ全体の Wiki を生成すると、トークンを非常に多く消費します。デフォルトでは対象範囲を限定してください。

• 初回スキャン：ディレクトリの深さは最大3階層
• モジュールごとのドキュメント：ユーザーが範囲を拡大しない限り、最大10モジュール
• ファイルの読み取り：ファイル全体を読むより、シンボルには search_files を使い、read_file には offset／limit を指定することを優先
• ベンダーコード（vendor/、third_party/、生成コード、_pb2.py、.min.js）は省略

ユーザーが「全体を徹底的にやって」と言った場合は、その意向に従います。ただし、まずはおおよそのコストを伝えてください。「このリポジトリにはソースファイルが約340個あります。包括的に網羅するとコストがかかりますが、よろしいですか？」

再実行／更新

対象パスに .codewiki-state.json がすでにある場合：

• 前回の SHA とモジュール一覧を読み取る
• ソースの SHA が一致する場合：再生成するか、スキップするかユーザーに確認する
• SHA が異なる場合：変更されたファイルのモジュールのみを再生成することを提案する（git diff --name-only <old-sha> HEAD）

完全な増分再生成は今後の機能です。現時点では、全体を再生成しても問題ありません。

注意点

• コンポーネントを捏造しないでください。 図のすべてのノードと、記載するすべての関数呼び出しは、ソースに存在している必要があります。書き込みの前に read_file を実行してください。自動生成ドキュメントで最も大きな失敗要因は、もっともらしい内容を捏造することです。
• 一般的すぎるAIの文章。 「このモジュールは〜を担当します」では内容がありません。モジュールが実際に何をするのかを、ドメインに即した具体的な用語で説明してください。
• コードの内容を文章で言い換えること。 「process 関数は、各アイテムに対して process_item を呼び出して処理します」と説明するモジュールのドキュメントは、その関数へのリンクを載せるだけよりも劣ります。
• Mermaidのノードが50個を超える場合。 読みやすく表示されません。分割してください。
• テスト、生成されたコード、ベンダー依存関係を製品コードとして文書化すること。 対象から除外してください。
• 確認せずにリポジトリ内へ出力すること。 デフォルトの出力先は ~/.hermes/wikis/ です。ユーザーから明示的に依頼された場合にのみ、リポジトリ内に書き込んでください。
• Mermaidでは特殊文字を引用符で囲む必要があります： A["Tool / Agent"] のように記述し、A[Tool / Agent] とはしないでください。ノード内の改行には <br> を使ってください。
• SKILL.md内にコードフェンスをネストする場合。 Mermaidブロックを含むMarkdownの例を書くときは、外側のフェンスに4つのバッククォートを使用してください。内側の3つのバッククォートによる ```mermaid が外側のフェンスを閉じないようにします。（このSKILL.mdではそのようにしています。）
• classDiagramのジェネリクスは <T> ではなく ~T~ として表示されます（例：List~Tool~）。
• GitHubのMermaidテーマは固定です — %%{init: ...}%% ブロックを含めないでください。レンダリング時に除去されます。

検証

書き込み後、次の項目を検証してください。

1. Mermaidブロックの対応が取れていること — ファイルごとに開始と終了の数が一致していること：

   for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
     opens=$(grep -c '^```mermaid' "$f")
     total=$(grep -c '^```' "$f")
     echo "$f: $opens mermaid blocks, $total total fences (expect total = opens*2)"
   done
   

2. 想定されるすべてのファイルが存在すること —

   ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
      "$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/
   

3. モジュール数が想定と一致すること — ls "$OUTPUT_DIR/modules" | wc -l の結果が、ステップ3で作成すると決めたモジュール数と一致していること。
4. パスが捏造されていないこと — ソースへのリンクを2〜3件確認し、実在するファイルに解決されることを確かめてください。