patchwork — Codebase Conventions for AI Agents

patchwork

Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.

Every team that uses AI coding assistants hits the same wall: Claude writes getUserById in a codebase that uses get_user_by_id. Cursor creates components/userCard.tsx in a project that uses user-card.tsx. The agent invented a response shape that doesn't match the rest of the API.

You write a CLAUDE.md manually. It goes stale in two weeks. You write it again.

patchwork automates this. It scans your actual source code using AST analysis and detects what your team really does — not what you think you do.

What it detects

Quick start

pip install patchwork-conventions
cd your-project
patchwork scan

That's it. You'll get a CONVENTIONS.md like this:

# 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

Why not argus or sourcebook?

Commands

# 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 integration

Option 1: CONVENTIONS.md (recommended)

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

Option 2: Append to CLAUDE.md

patchwork scan --claude-md

Option 3: MCP server

Claude Code — add to ~/.claude.json (or run claude mcp add interactively):

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

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor — add to .cursor/mcp.json in your project root:

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

Then your AI agent can use 8 on-demand tools:

Option 4: Claude Code skill (SKILL.md)

Copy SKILL.md from this repo to ~/.claude/skills/patchwork/SKILL.md to get /patchwork slash commands.

Watch mode (CI/auto-update)

# 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}")

Supported languages

Install full language support:

pip install 'patchwork-conventions[full]'

How it works

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)

All analysis is 100% local — no API calls, no telemetry, no data leaves your machine.

Performance

On a 1,000-file TypeScript monorepo:

• Without tree-sitter: ~0.8s
• With tree-sitter (full AST): ~2.1s

On a 500-file Python project:

• ~1.1s

Results are deterministic — same codebase always produces the same output.

Contributing

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

Pull requests welcome. See CONTRIBUTING.md.

License

MIT — free for personal and commercial use.

Topics

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