onboard-codebase

スキル：onboard-codebase

WHAT

目的とコンテキスト

• 目的： 未マッピングのコードベースを分析し、技術的・ビジネス上のコンテキストを抽出して、プロジェクトの標準に従って Wiki に反映します。
• 使用するタイミング：
  • レガシープロジェクトや既存プロジェクトにエージェント環境を導入するとき。
  • Wiki が古くなっているとき、または最近のコード変更によるコンテキストの欠落があるとき。
• 対象外： プロジェクトのコードは変更しません。## Origin を確認せずに手書きの Wiki ページを上書きしません。README やコメントを、コードに代わる事実として扱いません。

メンタルモデル

コードベース → インフラ監査 → ドメインロジック + パターン →（フロントエンドのスタイルがある場合）→ ビジネスルール → エンティティ → Wiki（エンティティ・コンセプト・fe-style・AGENT-business.md）→ インデックス + ログ → lint。

入力と出力の契約

	フィールド	必須？	意味
入力	プロジェクトのコードベース	はい	すべての主張を検証するために実装を読みます
出力	llmwiki/wiki/entities/project-structure.md	はい	ディレクトリ構造、スタック、エントリーポイント、ビルド／デプロイ
出力	llmwiki/wiki/concepts/*.md	はい	ドメインのコンセプト + パターン
出力	llmwiki/wiki/concepts/fe-style.md	フロントエンドがある場合	実際の値（hex、px/rem、クラス）
出力	AGENT-business.md	はい	コードから推定したユーザーストーリー + ビジネスルール
出力	llmwiki/wiki/entities/* + インデックス + ログ	はい	サービス、外部 API、DB テーブル
出力	ドラフトの出力レポート	はい	Delivery 項目

ルールと機能

• RULE-01（必須）：ビジネスに関する主張を検証するため、必ず実装を読みます。
• RULE-02（必須）：README.md／コメントと相互参照しますが、コード内の事実を優先します。
• RULE-03（必須）：「何を」だけでなく、コードレベルでの「なぜ」と「どのように」に重点を置きます。
• RULE-04（必須）：## Origin セクションを確認せずに、既存の手書き Wiki 項目を上書きしてはいけません。
• RULE-05（必須）：**OKF v0.1（R9）：**すべての Wiki ページは、空でない type（concept／entity／source）を含む YAML frontmatter（---）で始めます。該当する _template.md をコピーしてください。## Origin（R2）を保持してください。
• RULE-06（必須）：fe-style.md には、説明ではなく実際の値（hex コード、px/rem サイズ、クラス名）を記録します。推測せずに再現できるビジュアルスタイルを目指します。
• 機能：コードベース全体を読み取ること、llmwiki/wiki/ と AGENT-business.md に書き込むこと、Wiki の lint を実行すること。

失敗時の境界

• フロントエンドがない場合 → ステップ 3 を省略し、fe-style.md を作成しません（限定的な意味で成功）。
• 手書きの Wiki ページがすでにあり、## Origin で上書きが許可されていない場合 → 修正する前に確認します。
• コードで検証できないビジネス上の主張は、事実として記載しません。未検証であることを明記します。
• lint で矛盾が報告された場合 → ページを修正し、完了とみなす前に再実行します。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	codebase	インフラストラクチャ監査	project-structure.md	—
W02	judgment	code domain	コードの詳細分析（サービス、モデル、パターン）	concepts	—
W03	judgment	frontend	フロントエンドとスタイルの監査	fe-style.md	フロントエンドがない → スキップ（B01）
W04	judgment	code	ビジネスロジックの抽出	AGENT-business.md	検証できない主張 → 記載しない
W05	judgment	code	エンティティのカタログ化	entities	—
W06	effect	W01–W05 の結果	ナレッジの注入 + インデックス + ログ	Wiki を更新	手動作成ページ → ## Origin を確認
W07	deterministic	wiki	最終検証：lint	矛盾がない	矛盾がある → 修正して W07 を繰り返す

各ステップの詳細（W01–W07 の基準となる情報源）：

1. インフラストラクチャ監査：
   • ディレクトリ構造をマッピングします。
   • 技術スタック、エントリーポイント、ビルド／デプロイスクリプトを特定します。
   • llmwiki/wiki/entities/project-structure.md に保存します。
2. コードの詳細分析：
   • 中核となるドメインロジック（サービス、モデル、コントローラー）をスキャンします。
   • パターン（リポジトリ、イベント駆動など）を特定します。
   • llmwiki/wiki/concepts/ 用のコンセプトを抽出します。
3. フロントエンドとスタイルの監査（フロントエンドがない場合はスキップ）：
   • UI フレームワーク（Next.js、React、Vue など）と CSS の方式（Tailwind、CSS Modules、styled-components、SCSS）を特定します。
   • tailwind.config.*、CSS 変数、テーマファイルから、デザイントークン（カラーパレット、タイポグラフィのスケール、間隔、ブレークポイント）を抽出します。
   • コンポーネントライブラリ（shadcn/ui、MUI、Ant Design、Radix、Headless UI など）とローカルのラッパーを特定します。
   • グローバルスタイル（globals.css、ベースレイアウトファイル、フォントの読み込み方式）を追跡します。
   • コンポーネントの命名規則（PascalCase、機能別フォルダー、コンポーネントと同じ場所に置くストーリーなど）を記録します。
   • UI の状態管理（Zustand、Jotai、Context、Redux など）とデータ取得のパターン（React Query、SWR、サーバーアクションなど）を記録します。
   • ルーティングの規則（ファイルベース、ネストされたレイアウト、認証ガード）を記録します。
   • llmwiki/wiki/concepts/fe-style.md に保存します。
4. ビジネスロジックの抽出：
   • コードからユーザーストーリーとビジネスルールをリバースエンジニアリングします。
   • AGENT-business.md を生成／更新します。
5. エンティティのカタログ化：
   • 内部サービス、外部 API、データベーステーブルを列挙します。
   • llmwiki/wiki/entities/ にエントリーを作成します。
6. ナレッジの注入：
   • Wiki の構造に合わせて統合します。
   • llmwiki/wiki/index.md と llmwiki/wiki/log.md を更新します。
7. 最終検証：
   • 生成した Wiki に対して lint を実行し、矛盾がないか確認します。

分岐

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	conditional_required	プロジェクトにフロントエンドがある	ステップ 3「フロントエンドとスタイルの監査」を実行	フロントエンドがない → スキップ	W04
B02	conditional_required	対象の Wiki ページが既に存在し、手動作成されている	先に ## Origin を読み、手動の内容を上書きしない場合にのみ更新	判断できない → ユーザーに確認	W06

検証と停止条件

必須条件：lint で Wiki に矛盾が残っていないこと、すべてのページに frontmatter の type と ## Origin があること（R2/R9）。要レビュー：ビジネス上の主張は、読み取ったコードまで遡って確認できること。W07 が成功し、出力レポートを作成したら停止します。

例

• 成功例： Next.js + Go のリポジトリをオンボーディングする → project-structure.md（スタック、エントリー、ビルド）、ドメインのコンセプト、#0F172A、text-sm／14px、shadcn/ui を記載した fe-style.md、AGENT-business.md、DB テーブルのエンティティ → lint がクリーン → レポートのドラフトを作成。
• 境界条件／失敗例： Go のバックエンドのみのリポジトリ → ステップ 3 を省略し、fe-style.md は作成しない。README に「返金に対応」と書かれていても、コードに返金ハンドラーがない → AGENT-business.md に事実として記載しない。

提出 — 出力レポート

メインのスキルタスクがすべて完了したら、Wiki に提案用のドラフトを書き込みます。

手順

1. ファイル名を作成します：

• 形式：DDMMYY-<ten>.md
• DDMMYY = 今日の日付（例：2026 年 6 月 2 日なら 020626）
• <ten> = 実施内容を要約する、ケバブケースの 2～4 語（例：landing-page-coteccons、brand-kit-fintech、ingest-auth-spec）

2. llmwiki/wiki/sources/draft/DDMMYY-<ten>.md を作成します：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. Wiki のインデックスとログを更新します：

• llmwiki/wiki/index.md — 次の行を 1 行追加します：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 次の行を追加します：## YYYY-MM-DD — <skill-name> — <ten>

スキルが成果物も決定事項も一切生成しない場合（例：/caveman-stats のような表示のみのモード）に限り、スキップしてください。