patchwork — Codebase Conventions Skill

This skill teaches you how to read and apply a CONVENTIONS.md file generated by patchwork. When this file exists in a project, always read it before writing any code.

Rule 1: Always read CONVENTIONS.md first

Before writing any new code, function, class, or file in a project, check if CONVENTIONS.md exists:

read_file("CONVENTIONS.md")

If it exists, extract and apply every convention listed in it. Do not guess or use generic defaults.

Rule 2: Apply naming conventions exactly

The Naming Conventions section tells you the exact casing style and confidence level. Follow the highest-confidence style.

If confidence is below 80%, flag the inconsistency to the user before writing.

Rule 3: Apply error handling patterns

The Error Handling section tells you how this project handles errors. Match it exactly.

• If pattern: try/except → always use try/except, never return error tuples
• If propagation: raise → re-raise exceptions, don't swallow them
• If custom exception naming: Error suffix → name new exceptions SomethingError, not SomethingException
• If custom exceptions are listed (e.g. UserNotFoundError) → extend those base classes, don't create new hierarchies

Rule 4: Apply testing conventions

The Testing Conventions section tells you how tests are written. Never deviate.

• If framework: pytest → write def test_...(): functions, never unittest.TestCase
• If assertions: assert → use plain assert, not assertEqual
• If mocking: patch → use unittest.mock.patch, not raw MagicMock
• If organisation: function-based → don't wrap tests in classes
• If test layout: separate → put tests in tests/, not next to source files

Rule 5: Apply API and async patterns

The API Patterns section tells you the framework and style in use.

• If framework: FastAPI + async style: async/await → all route handlers must be async def
• If route params: {id} → use {param} style in route paths, not :param
• If route params: :id → use Express-style :param
• If response shape: {data, error} → all responses must follow that exact shape

Rule 6: Apply import style

The Import Conventions section tells you how imports are organised.

• If style: absolute imports → never use relative imports like from ..utils import x
• If path aliases: src/ → use from src.module import x
• If key dependencies are listed → use those exact packages, don't introduce alternatives

Rule 7: Apply project structure

The Project Structure section tells you where to put new files.

• If tests: separate (tests/) → all test files go in tests/, not inline
• If organisation: flat-based → don't create feature subdirectories
• If organisation: feature-based → group by feature, not by type
• If source root: src/ → all source code goes under src/

Rule 8: Check symbol names before writing

Before finalising any function, class, variable, or file name, validate it against the conventions:

1. Is the casing correct? (snake_case / PascalCase / camelCase)
2. If it's a test function, does it start with test_?
3. If it's private, does it start with _?
4. If it's an exception class, does it end with Error?
5. If it's a new file, is the file name in the right case?

Correct any name that fails before writing the code.

Rule 9: Don't introduce new patterns

Even if you think a different pattern is better:

• Don't switch from pytest to unittest
• Don't add a new HTTP client if one is already listed in the stack
• Don't use a different assertion style
• Don't create a new exception base class if existing ones cover it

Consistency with the existing codebase is more important than your preference.

Rule 10: When CONVENTIONS.md is missing

If no CONVENTIONS.md exists, scan existing files before writing:

1. Look at 3–5 existing files in the same module
2. Match the naming style, import style, and error handling you see
3. Tell the user: "No CONVENTIONS.md found — following patterns from existing files"

You can suggest generating one:

pip install patchwork-conventions
patchwork scan .