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