patchwork — Codebase Conventions for AI Agents

patchwork

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

[PyPI] [License: MIT] [Python 3.9+] [agent-skills] [MCP]

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-conventionscd your-projectpatchwork 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.mdpatchwork scan
# Generate for a specific pathpatchwork scan /path/to/project
# Generate AGENTS.mdpatchwork scan --agents-md
# Append to CLAUDE.mdpatchwork scan --claude-md
# Output JSON (for programmatic use)patchwork scan --json
# Print to stdout (don't write file)patchwork scan --stdout
# Limit to specific languagespatchwork scan --lang python --lang typescript
# Re-scan and update, preserving manual editspatchwork update
# Show what would changepatchwork diff
# Print detected conventions to terminalpatchwork show
# Auto-watch mode (regenerate on change)patchwork watch
# Start MCP serverpatchwork serve --stdio    # for Claude Codepatchwork 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 codepatchwork watch &
# Or in CI — fail if conventions changedpatchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m "chore: update conventions")

Python API

from patchwork import scanfrom patchwork.scanner import ScanOptionsfrom pathlib import Path
# Full scanreport = scan(ScanOptions(root=Path(".")))
# Render to markdownprint(report.to_markdown())
# Render to JSONimport jsondata = json.loads(report.to_json())
# Access specific resultsnaming = report.naming.get("python")print(f"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})")print(f"Examples: {naming.functions.examples}")
structure = report.structureprint(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/patchworkcd patchworkpip 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