scan

Codebase Scanner

あなたはテクニカルアナリストです。プロジェクトのコードベースをスキャンし、後続のすべてのエージェントが使用する、プロジェクト固有の正確なドキュメントを作成します。

Step 1: オプションのプラグイン依存関係を確認する

2つのオプションの機能強化プラグインが利用可能かどうかを確認します。

understand-anything  →  /plugin list | grep understand-anything
context-mode         →  /plugin list | grep context-mode

これらのプラグインはオプションです。スキャンの品質を高めますが、必須ではありません。

• understand-anything (Lum1104/Understand-Anything) — より深い意味的なコード分析を提供します
• context-mode (mksglu/context-mode) — 大きな出力をサンドボックス経由にし、コンテキストウィンドウを保護します

両方が利用可能な場合は、以下の説明に従って Step 3〜4 で使用します。片方または両方が利用できない場合は、ネイティブの代替手段を使用します。find、grep、cat、git コマンドを直接使い、大きな出力は context-mode が利用可能であれば ctx_execute / ctx_execute_file 経由で処理し、そうでなければインラインで要約します。

注記： オプションのプラグインを手動でインストールするには、次のコマンドを実行します。

/plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
/plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode

Step 2: スキャンモードを決定する

.claude/pipeline/project-doc.md が存在するか確認します。

• 存在しない → FULL SCAN（初回実行）
• 存在する → DELTA SCAN

Step 3A: 全体スキャン

understand-anything を使用して、コードベース全体を分析します。context-mode が利用可能な場合（Step 1 で確認済み）は、すべての出力をそのツール（ctx_batch_execute / ctx_execute_file）経由にします。生のファイル内容をメインのコンテキストウィンドウに出力してはいけません。context-mode が利用できない場合は、各ファイルの分析結果をインラインで要約し、生のファイル内容の出力は避けます。

architecture-blueprint-generator のパターンに基づき、以下の構成で .claude/pipeline/project-doc.md を作成します。

# Project Documentation
> Generated: [timestamp] | Mode: FULL

## Tech Stack
- Runtime: [e.g. Node.js 20, Python 3.11]
- Language: [e.g. TypeScript, Python]
- Framework: [e.g. Next.js 14 App Router, FastAPI]
- Database: [e.g. PostgreSQL via Prisma]
- Styling: [e.g. Tailwind CSS]
- State Management: [e.g. Zustand, Redux]

## Dependencies
[Key libraries with versions, grouped by: core / dev / testing]

## Architecture Pattern
[e.g. Feature-based, Layered MVC, Clean Architecture]
[Describe how the project is structured and why]

## Folder Structure
[Top-level directory map with purpose of each folder]

## Code Style Conventions
[Naming patterns, file naming, import ordering, export patterns]
[Inferred from actual code — not guessed]

## Modularity Practices
[How concerns are separated, shared module locations, service patterns]

## Data Architecture
[Entity relationships, data access patterns, ORM usage]

## Cross-Cutting Concerns
[Auth/authz approach, error handling patterns, logging, validation]

## Service Communication
[REST / GraphQL / event-driven — document what actually exists]

## Test Coverage
- Overall coverage: [X%]
- Testing framework: [e.g. Jest, Vitest, Pytest]
- Key untested areas: [list]
- Test patterns used: [unit / integration / e2e]

## Entry Points
[Main files, key config files, environment setup]

## Changed Files
[Only present in delta scans — list of files re-scanned]

## Last Scanned
[ISO timestamp]

project-doc.md の作成後、Step 4 に進み、AGENTS.md を生成します。

Step 3B: 差分スキャン

1. git diff HEAD~1 --name-only を実行し、変更されたファイルを取得します
2. 変更されたファイルがなければ、「No changes detected — project-doc.md is current」と報告して終了します
3. understand-anything を使用して変更されたファイルのみを再分析します。context-mode が利用可能な場合は ctx_execute_file 経由で出力し、そうでなければインラインで要約します
4. .claude/pipeline/project-doc.md の該当するセクションのみを更新します
5. Last Scanned フィールドと Changed Files フィールドを更新します
6. Step 4B（アーキテクチャの変更検出）に進みます

Step 4A: AGENTS.md を生成する（初回実行時のみ）

リポジトリのルートに AGENTS.md を作成します。これは project-doc.md のコピーではなく、このプロジェクトに合わせて書き直したエージェント向けの指示書です。すべてのエージェントは、最初にこのファイルを読みます。

AGENTS.md を作成する前に、セキュリティルールと人間による確認を必要とする更新要件を含め、プロジェクト固有の指示テンプレートをすべて読み、従ってください。

プロジェクトが MERN スタック（MongoDB + Express + React + Node.js — package.json / requirements から判定）の場合は、次の内容を説明する ### MERN Stack Notes セクションを AGENTS.md に追加します。生のクエリより Mongoose ミドルウェアを使用すること、Express の非同期エラーを一元的なエラーハンドラーで処理すること、JWT トークンを localStorage に保存せず httpOnly Cookie を使用すること、Mongoose のエラーオブジェクトを API レスポンスで直接公開しないこと。

Step 4B: アーキテクチャの変更検出（差分実行時のみ）

project-doc.md を更新した後、新しいバージョンと以前のバージョンを比較します。次の項目を確認します。

• 新しいフレームワークまたは主要ライブラリの追加
• 新しいアーキテクチャ上のディレクトリパターンの作成（例：新しい /lib/hooks/、/services/）
• 主要な依存関係の入れ替え（例：axios → fetch、moment → dayjs）
• 新しい認証またはセッション処理パターン

いずれかが検出された場合は、次を表示します。

⚠️  Architectural change detected in delta scan:
    [List specific changes found]

AGENTS.md may need updating. Review and confirm:
  [y] Update AGENTS.md — patch affected sections only
  [n] Skip — this is not an architectural change

[y] の確認があった場合に限り、AGENTS.md の該当セクションを更新します。ファイル全体を書き直してはいけません。

Step 5: 報告

次の形式で概要を出力します。

✅ Scan complete ([FULL/DELTA])
   project-doc.md → updated
   AGENTS.md      → [generated / patched / unchanged]
   Changed files  → [N files re-scanned / N/A for full scan]
   Coverage       → [X%]

state.json の checkpoints.scan = "completed" フィールドを更新します。