patchwork — Codebase Conventions for AI Agents

patchwork

コードベースを調査して、CONVENTIONS.md を生成します。AI エージェントが独自のスタイルを作り出すのを防ぎます。

---

AI コーディングアシスタントを使うチームなら、誰もが同じ壁にぶつかります。get_user_by_id を使うコードベースで Claude が getUserById を書き、user-card.tsx を使うプロジェクトで Cursor が components/userCard.tsx を作成します。エージェントは、API の他の部分と一致しないレスポンス形式を勝手に作り出します。

CLAUDE.md を手動で書いても、2 週間後には古くなります。もう一度書き直すことになります。

patchwork はこの作業を自動化します。 AST 解析を使って実際のソースコードをスキャンし、チームが実際に採用しているスタイルを検出します。チームが採用していると思っているスタイルではありません。

---

検出できる項目

カテゴリ	調査内容
命名	関数、クラス、変数、定数、ファイル — 信頼度スコアと実例付き
インポート	絶対パスか相対パスか、パスエイリアス（@/、src/）、バレルファイル、分割代入のスタイル
構成	ソースルート、テスト構成、機能別かレイヤー別かの編成、モノレポの検出
エラー処理	try/except か Result 型か、ロギングフレームワーク、カスタム例外の命名、伝播スタイル
テスト	フレームワーク、アサーションスタイル、モックライブラリ、カバレッジツール、フィクスチャのパターン
API パターン	レスポンス形式、ルートパラメーターのスタイル、ORM、非同期パターン、GraphQL/gRPC の有無
Git ワークフロー	コミットメッセージのスタイル、ブランチの命名、同時に変更されるファイルのペア
技術スタック	フレームワーク、パッケージマネージャー、リンター、フォーマッター、型チェッカー、ビルドツール、スクリプト

---

クイックスタート

pip install patchwork-conventions
cd your-project
patchwork scan

これだけです。次のような CONVENTIONS.md が生成されます。

# CONVENTIONS.md
> Auto-generated by patchwork on 2026-06-25

## Tech Stack
**Language:** python
**Runtime:** Python >=3.11
**Package Manager:** uv
**Frameworks:** fastapi, sqlalchemy
**Linters:** ruff
**Formatters:** ruff, black

## Naming Conventions

### Python
- **Functions:** `snake_case` (97% consistent)
  - Examples: `get_user`, `parse_response`, `create_session`
- **Classes:** `PascalCase` (100% consistent)
  - Examples: `UserService`, `AuthHandler`, `DatabaseClient`
- **Constants:** `SCREAMING_SNAKE`
  - Examples: `MAX_RETRIES`, `API_BASE_URL`
- **Files:** `snake_case`
- **Private prefix:** `_`
- **Test functions:** prefix `test_`

## Project Structure
**Source root:** `src/`
**Organisation:** layer-based
**Tests:** separate (`tests/`)

**Key directories:**
  - `src/` — source root
  - `tests/` — test suite
  - `migrations/` — database migrations

## Error Handling

### Python
- **Pattern:** try/except
- **Propagation:** raise
- **Logging:** `structlog`
- **Custom exception naming:** Error suffix
  - `ValidationError`, `AuthError`, `NotFoundError`

## Testing Conventions

### Python
- **Framework:** pytest
- **Coverage:** 34 test files / 89 source files (38% ratio)
- **Assertions:** `assert(...)`
- **Coverage tool:** `pytest-cov`
- **Patterns:** fixtures, factories

## Git Conventions
- **Commit style:** conventional commits
- **Examples:** `feat(auth): add JWT refresh`, `fix(api): handle null user`
- **Branch naming:** feature/name + fix/name

---

argus や sourcebook ではなく、patchwork を選ぶ理由

機能	patchwork	argus	sourcebook
AST ベースの命名解析	✅ tree-sitter	❌ ファイルシステムのみ	❌ 未実装
信頼度スコア	✅ カテゴリごと	❌	❌
コードからの実例	✅	❌	❌
反例（不整合）	✅	❌	❌
エラー処理パターンの調査	✅	❌	❌
API レスポンス形式の検出	✅	❌	❌
同時変更ファイルのペア	✅	❌	✅
規約チェック（check コマンド）	✅	❌	❌
8 つのツールを備えた MCP サーバー	✅	❌	✅（4 つのツール）
監視モード	✅	✅（sync）	✅
LLM 不要	✅	✅	✅（レイヤー A）
オープンソース / MIT	✅	✅	❌ BSL

---

コマンド

# Generate CONVENTIONS.md
patchwork scan

# Generate for a specific path
patchwork scan /path/to/project

# Generate AGENTS.md
patchwork scan --agents-md

# Append to CLAUDE.md
patchwork scan --claude-md

# Output JSON (for programmatic use)
patchwork scan --json

# Print to stdout (don't write file)
patchwork scan --stdout

# Limit to specific languages
patchwork scan --lang python --lang typescript

# Re-scan and update, preserving manual edits
patchwork update

# Show what would change
patchwork diff

# Print detected conventions to terminal
patchwork show

# Auto-watch mode (regenerate on change)
patchwork watch

# Start MCP server
patchwork serve --stdio    # for Claude Code
patchwork serve --port 3742  # HTTP mode

---

Claude Code との連携

オプション 1：CONVENTIONS.md（推奨）

patchwork scan      # run once
# CONVENTIONS.md is automatically read by Claude Code

オプション 2：CLAUDE.md に追記する

patchwork scan --claude-md

オプション 3：MCP サーバー

Claude Code — ~/.claude.json に追加します（または claude mcp add を対話形式で実行します）。

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", "/path/to/your/project", "--stdio"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", "/path/to/your/project", "--stdio"]
    }
  }
}

Cursor — プロジェクトのルートにある .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "patchwork": {
      "command": "patchwork",
      "args": ["serve", ".", "--stdio"]
    }
  }
}

その後、AI エージェントは必要に応じて次の 8 つのツールを使用できます。

ツール	使用するタイミング
patchwork_scan	規約の全体像を把握するとき
patchwork_naming	新しい識別子を書く前
patchwork_structure	新しいファイルやディレクトリを作成する前
patchwork_stack	ライブラリやコマンドを選ぶとき
patchwork_errors	エラー処理を書く前
patchwork_testing	テストファイルを書く前
patchwork_git	コミットメッセージを書く前
patchwork_check	提案した名前を検証するとき

オプション 4：Claude Code スキル（SKILL.md）

このリポジトリの SKILL.md を ~/.claude/skills/patchwork/SKILL.md にコピーすると、/patchwork スラッシュコマンドを使用できます。

---

ウォッチモード（CI／自動更新）

# Keep CONVENTIONS.md updated as you code
patchwork watch &

# Or in CI — fail if conventions changed
patchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m "chore: update conventions")

---

Python API

from patchwork import scan
from patchwork.scanner import ScanOptions
from pathlib import Path

# Full scan
report = scan(ScanOptions(root=Path(".")))

# Render to markdown
print(report.to_markdown())

# Render to JSON
import json
data = json.loads(report.to_json())

# Access specific results
naming = report.naming.get("python")
print(f"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})")
print(f"Examples: {naming.functions.examples}")

structure = report.structure
print(f"Source root: {structure.source_root}")
print(f"Organisation: {structure.organisation}")

---

サポートされている言語

言語	AST（tree-sitter）	フォールバック正規表現
Python	✅ 完全対応	✅
TypeScript	✅ 完全対応	✅
JavaScript	✅ 完全対応	✅
Go	✅（full extra が必要）	✅
Rust	✅（full extra が必要）	✅
Java	✅（full extra が必要）	✅
Ruby、PHP、C#、C++	❌	✅ 正規表現のみ

言語の完全なサポートをインストールするには：

pip install 'patchwork-conventions[full]'

---

仕組み

your codebase
     │
     ▼
ConfigDetector        ← reads package.json, pyproject.toml, go.mod, Cargo.toml
     │
     ▼
File discovery        ← respects .gitignore, skips node_modules etc.
     │
     ▼
Per-language AST      ← tree-sitter parses every file into a syntax tree
     │
     ├── NamingMiner       → extracts function/class/variable names, classifies style
     ├── ImportMiner        → detects import patterns, aliases, barrel files
     ├── StructureMiner     → analyses directory layout, test co-location
     ├── ErrorHandlingMiner → detects try/catch patterns, logging, custom exceptions
     ├── TestingMiner       → identifies framework, assertion style, mocking
     ├── APIPatternMiner    → finds response shapes, ORMs, route styles
     └── GitPatternMiner    → mines commit history, branches, co-change pairs
          │
          ▼
     ConventionReport
          │
          ├── CONVENTIONS.md  (default)
          ├── AGENTS.md       (--agents-md)
          ├── CLAUDE.md       (--claude-md, appends)
          └── JSON            (--json)

すべての分析は100％ローカルで行われます。API 呼び出しもテレメトリもなく、データがマシンの外に送信されることはありません。

---

パフォーマンス

1,000 ファイルの TypeScript モノレポの場合：

• tree-sitter なし：約0.8秒
• tree-sitter あり（完全な AST）：約2.1秒

500 ファイルの Python プロジェクトの場合：

• 約1.1秒

結果は決定論的です。同じコードベースからは常に同じ出力が得られます。

---

コントリビューション

git clone https://github.com/yourusername/patchwork
cd patchwork
pip install -e '.[dev]'
pytest

プルリクエストを歓迎します。CONTRIBUTING.md を参照してください。

---

トピック

claude-code · agent-skills · mcp · context-engineering · hallucination-detection · code-conventions · static-analysis · tree-sitter · developer-tools · ai-coding