Agent Smith

┏━┓┏━╸┏━╸┏┓╻╺┳╸   ┏━┓┏┳┓╻╺┳╸╻ ╻
┣━┫┃╺┓┣╸ ┃┗┫ ┃    ┗━┓┃┃┃┃ ┃ ┣━┫
╹ ╹┗━┛┗━╸╹ ╹ ╹    ┗━┛╹ ╹╹ ╹ ╹ ╹

agentsmith

コードベースから AGENTS.md を自動生成

AGENTS.md を手作業で書くのはやめましょう。agentsmith を実行すると、コードベースをスキャンして、AI コーディングツールが自動的に読み込む包括的なコンテキストファイルを生成します。

AGENTS.md とは？

AGENTS.md は、AI コーディングアシスタントにプロジェクトのコンテキストを伝えるためのオープンスタンダードです。60,000 以上のプロジェクトで採用されており、次のツールでサポートされています。

• Cursor
• GitHub Copilot
• Claude Code
• VS Code
• Gemini CLI
• その他 20 以上のツール

AI ツールは AGENTS.md ファイルを自動的に検出して読み込むため、設定は不要です。

agentsmith の機能

AGENTS.md を手作業で書く代わりに、agentsmith がコードベースをスキャンして生成します。

npx @jpoindexter/agent-smith

  agentsmith

  Scanning /Users/you/my-project...

  ✓ Found 279 components
  ✓ Found 5 components with CVA variants
  ✓ Found 37 color tokens
  ✓ Found 14 custom hooks
  ✓ Found 46 API routes (8 with schemas)
  ✓ Found 87 environment variables
  ✓ Detected Next.js (App Router)
  ✓ Detected shadcn/ui (26 Radix packages)
  ✓ Found cn() utility
  ✓ Found mode/design-system
  ✓ Detected 6 code patterns
  ✓ Found existing CLAUDE.md
  ✓ Found .ai/ folder (12 files)
  ✓ Found prisma schema (28 models)
  ✓ Scanned 1572 files (11.0 MB, 365,599 lines)
  ✓ Found 17 barrel exports
  ✓ Found 15 hub files (most imported)
  ✓ Found 20 Props types
  ✓ Found 40 test files (12% component coverage)

  ✓ Generated AGENTS.md
    ~11K tokens (9% of 128K context)
    Help improve agentsmith → github.com/jpoindexter/agentsmith/issues

インストール

# Run directly (no install needed)
npx @jpoindexter/agent-smith

# Or install globally
npm install -g @jpoindexter/agent-smith

使い方

# Generate AGENTS.md in current directory
agentsmith

# Generate for a specific directory
agentsmith ./my-project

# Preview without writing (dry run)
agentsmith --dry-run

# Custom output file
agentsmith --output CONTEXT.md

# Force overwrite existing file
agentsmith --force

フィードバックとバグ報告

agentsmith feedback

バグ、アイデア、質問、または取り組んでいることの共有など、どんなフィードバックも役立ちます。

agentsmith feedback を実行し、希望する操作を選択してください。バグの報告、機能のリクエスト、質問、アイデアの共有、作成したものの紹介ができます。バグ報告では診断情報が自動的に収集され、課題の内容が事前に入力されます。

プライバシー： agentsmith はデータを収集、送信、保存しません。すべてお使いのマシン上でローカルに実行されます。フィードバックコマンドでは、バグ報告に役立てるための基本情報（ツールのバージョン、OS、ファイル数の集計）が収集されますが、自動的に外部へ送信されることはありません。収集される情報はすべて確認でき、含めるかどうかはご自身で選択できます。ログを共有したくない場合は、簡単な説明だけでも大いに役立ちます。

次の方法で直接お問い合わせいただくこともできます。

• バグを報告
• 機能をリクエスト
• 質問する
• アイデアを共有
• 作成したものを紹介

出力モード

# Default - comprehensive output (~11K tokens)
agentsmith

# Compact - fewer details (~20% smaller)
agentsmith --compact

# Compress - signatures only (~40% smaller)
agentsmith --compress

# Minimal - ultra-compact (~3K tokens)
agentsmith --minimal

# XML format (industry standard, matches Repomix)
agentsmith --xml

# Include file tree visualization
agentsmith --tree

v1.1 の新機能

🎯 API スキーマ抽出

API ルートからZod バリデーションスキーマとTypeScript 型を検出するようになりました。

- `POST` `/api/contact`
  - **Request**: contactSchema {
      name: string (max: 100, min: 1, "Name is required")
      email: string (email: Invalid email address)
      subject: "sales" | "support" | "billing" | ...
    }

AI エージェントは、フィールド名を推測する代わりに API コントラクトを確認できるようになります。

🧠 認知的複雑度分析

コードベースの複雑度を分析し、AI モデルの適切な努力レベルを提案します。

**Complexity by Area:**
- 🔴 Database: Maximum effort (most capable model)
- 🟡 API Routes: Standard effort (balanced model)
- 🟢 Utilities: Minimal effort (fast, low-cost model)

🚀 パフォーマンスの向上

• グローバルスキーマキャッシュ：O(n²) → O(n)（共有スキーマの場合）
• 大規模なコードベースで20～40％高速化

🌐 GraphQL のサポート

.graphql ファイルと .gql ファイルから GraphQL スキーマ定義を抽出します。

🤖 AI プロバイダーに依存しない推奨

あらゆる AI プロバイダー（Claude、GPT、Gemini）で動作します。モデル名はハードコードされていません。

v1.0.0 の新機能

# Copy output to clipboard
agentsmith --copy

# Include uncommitted git changes
agentsmith --include-diffs

# Split large repos into chunks
agentsmith --split-output 100kb   # Creates AGENTS-001.md, AGENTS-002.md, etc.

# Include security audit (npm audit)
agentsmith --security

# Monorepo support - generate for each package
agentsmith --monorepo

# Start as MCP server for AI tool integration
agentsmith --mcp

すべてのオプション

フラグ	説明
-o, --output <file>	出力ファイルのパス（デフォルト：AGENTS.md）
--dry-run	ファイルに書き込まずにプレビュー
--force	既存の AGENTS.md を上書き
--compact	詳細を減らし、サイズを約 20％縮小
--compress	シグネチャのみを出力し、サイズを約 40％縮小
--minimal	超コンパクト（約 3K トークン）
--xml	XML 形式で出力
--tree	ファイルツリーを含める
--json	AGENTS.index.json も生成
--copy	出力をクリップボードにコピー
--include-diffs	未コミットの Git 変更を含める
--include-git-log	最近のコミットを含める
--split-output <size>	チャンクに分割（例：100kb）
--security	npm audit の結果を含める
--monorepo	各ワークスペースパッケージ向けに生成
--mcp	MCP サーバーとして起動
--remote <url>	GitHub リポジトリを分析
--watch	ファイル変更時に自動再生成
--check-secrets	出力前にシークレットをスキャン

サブコマンド：

コマンド	説明
agentsmith feedback	診断情報を自動収集して事前入力した GitHub の課題を開く

MCP サーバーモード

agentsmith は、AI ツールを統合するための MCP（Model Context Protocol）サーバーとして実行できます。

agentsmith --mcp

AI アシスタント向けの16 個のツール：

カテゴリ	ツール
コア	pack_codebase、read_agents
コンポーネント	search_components、get_component_info
API	get_api_routes、get_route_details、search_routes
データベース	get_database_models、get_model_details
GraphQL	get_graphql_schemas
複雑度	get_complexity_report、get_complex_files
フック	get_hooks、get_hook_details
検索	search_codebase、get_file_info

5 つの MCP リソース（キャッシュ付きライブサブスクリプション）：

• agents://agents-md - 自動生成された AGENTS.md
• agents://api-schemas - すべての API ルートスキーマ
• agents://database-schema - フィールドとリレーションを含むデータベースモデル
• agents://graphql-schemas - GraphQL 型定義
• agents://complexity-report - コードベースの複雑度分析

設定

プロジェクトのルートに agentsmith.config.json を作成します。

{
  "output": "AGENTS.md",
  "exclude": [
    "**/test/**",
    "**/stories/**",
    "**/fixtures/**"
  ]
}

スキャン対象

スキャナー	検出内容
コンポーネント	エクスポート、props、JSDoc、複雑度メトリクスを含む React コンポーネント
バリアント	CVA のバリアントオプション（Button：default、destructive など）
依存関係	コンポーネントのインポート（radix、デザインシステム、ユーティリティ）
バレル	推奨されるインポートパスのための Index.ts の再エクスポート
トークン	CSS 変数と Tailwind の設定
フック	クライアント専用かどうかの検出を含むカスタムフック
API ルート	メソッドと認証状態を含む Next.js ルート
API スキーマ	リクエスト／レスポンス用の Zod 検証スキーマと TypeScript 型
GraphQL	.graphql/.gql ファイルの GraphQL スキーマ定義
データベース	フィールドとリレーションを含む Prisma および Drizzle モデル
環境	.env.example から取得した必須／任意の環境変数
パターン	react-hook-form、Zod、Zustand、tRPC、テストライブラリ
ユーティリティ	cn()、mode／デザインシステムの検出
フレームワーク	バージョンとルーターの種類を含む Next.js、Remix、Vite
複雑度	AI モデルの推奨用の認知的複雑度分析
統計	ファイル数、行数、サイズ、最大のファイル
既存ドキュメント	CLAUDE.md、.ai/ フォルダー、.cursorrules
ファイルツリー	プロジェクト構造の可視化
インポートグラフ	ハブファイル、循環依存、未使用コンポーネント
TypeScript	props インターフェース、API 型、モデル型
テスト	テストフレームワークの検出、カバレッジのマッピング
セキュリティ	npm audit の脆弱性、古いパッケージ

出力

生成される AGENTS.md には、以下が含まれます。

• TL;DR - スタック、コンポーネント数、主要なインポート、影響の大きいファイル
• はじめに - 自動生成されたセットアップ手順
• プロジェクト概要 - フレームワーク、言語、スタイル、統計
• 重要なルール - 誤った／正しいコード例付き
• コンポーネント - カテゴリ別にまとめた全コンポーネント一覧
• ハブファイル - 最も多くインポートされるファイル（変更の影響が広範囲に及びます）
• 未使用コンポーネント - 未使用コードの可能性に関する警告
• 推奨されるインポート - コードを整理するためのバレルインポート
• カスタムフック - クライアント専用マーカー付き
• API ルート - パス別にまとめたメソッド、認証、リクエスト／レスポンススキーマ
• GraphQL スキーマ - .graphql/.gql ファイルの型定義
• データベースモデル - フィールドとリレーション
• 環境変数 - 必須と任意
• コードパターン - 検出されたパターンと例
• デザイントークン - 使用方法のガイダンス付きカラー�ークン
• AI の推奨事項 - コードベースの複雑度に基づくモデルの作業量レベル
• コマンド - npm スクリプト
• セキュリティ - 脆弱性と古いパッケージ（--security 指定時）

出力例

# AGENTS.md

> Auto-generated by agentsmith

## TL;DR

- **Stack**: Next.js 16.0.10 + TypeScript 5 + Tailwind 4.0.9 + shadcn/ui
- **Components**: 279 total — USE EXISTING, don't create new
- **Key imports**: `cn()` from `@/lib/utils`, `mode` from `@/design-system`
- **High-impact files**: design-system/index, utils, button, card
- **Database**: prisma with 28 models
- **API**: 46 routes (31 protected)

## Getting Started

```bash
npm install

# Set up environment
cp .env.example .env.local

# Database setup
npm run db:push
npm run db:seed

# Start development
npm run dev

重要なルール

1. 既存のコンポーネントを使用する

// WRONG
<div className="rounded border p-4">...</div>

// RIGHT
<Card><CardContent>...</CardContent></Card>

2. デザイントークンを使用する

// WRONG
className="bg-blue-500 text-white"

// RIGHT
className="bg-primary text-primary-foreground"

## Why?

AI coding tools work better when they understand your codebase:

- ❌ AI generates `bg-blue-500` instead of your `bg-primary` token
- ❌ AI creates a new Button when you already have one with 9 variants
- ❌ AI ignores your patterns and conventions

With AGENTS.md:

- ✅ AI knows your components and uses them
- ✅ AI follows your design tokens
- ✅ AI matches your patterns

## Comparison

| Tool | Focus | Approach |
|------|-------|----------|
| **agentsmith** | AGENTS.md generation | Scans codebase, generates context |
| Repomix | Code packing | Packs files into single XML |
| Code2Prompt | Prompt building | Builds prompts from code |

agentsmith is specifically designed for the AGENTS.md standard with opinionated rules about component reuse and design tokens.

## Works great in

- Next.js + Tailwind + shadcn/ui projects
- React apps with component libraries
- Any TypeScript codebase with reusable components

## License

MIT

---

A [theft.studio](https://theft.studio) project