Setup¶
You can configure Claude Code in the CLAUDE.md file. Most other agents, however, use AGENTS.md. Generally speaking, though, you shouldn’t simply copy an existing configuration file;
Warning
Anthropic recommends a maximum of 200 lines; see My CLAUDE.md is too large.
Cross-agent configuration¶
If you want to support multiple agents in your projects, you can simply use
@AGENTS.md in CLAUDE.md to reference the configuration in your
AGENTS.md file.
See also
General approach¶
I usually like to have five proposed solutions put forward first, before implementing the one that is likely to be the most effective:
# General procedure
- Before creating code, brainstorm 5 different approaches to solve the problem and sort them by their probable effectiveness. Then, choose the best approach and implement it.
uv¶
Many agents typically use pip when installing packages or running scripts. A
CLAUDE.md
or AGENTS.md file in your project’s root directory overrides this
default setting, so that uv is
used instead in every session. One possible configuration for an
AGENTS.md file is:
- Use `uv` to manage Python environments and dependencies.
- Use `uv run` to execute Python scripts and commands.
- Don't edit `pyproject.toml` directly. Instead, use `uv add` and `uv add --dev` to manage dependencies.
Code quality and linting¶
We usually check code quality and syntax using tools such as Ruff, ty, prek and Wily.
# Code quality and linting
- Use ruff, ty, prek, wily for code quality and linting.
- Run appropriate tooling after making changes to your code to ensure it meets quality standards.
Typing¶
Avoid excessive type conversions. If you find that type conversions occur frequently in the code, the code should be refactored to use more appropriate types. Ideally, type conversions should only be performed at interfaces with external systems. Use type hints for all function parameters and return types.
# Typing
- Don't use excessive casting. If you find yourself needing to cast types frequently, consider refactoring your code to use more appropriate types. Casting should only be done in boundary layers where you are interfacing with external systems.
- Use type hints for all function parameters and return types.
Testing¶
Many of our projects use Test-Driven Development with pytest and Hypothesis. Furthermore, mocking and monkeypatch should be avoided.
# Testing
- Use `pytest` for testing your code.
- Collect pytest fixtures in a `conftest.py` file to avoid duplication.
- Use the `hypothesis` library for property-based testing when you have complex input spaces or need to test edge cases.
- Favor pytest monkeypatch to mock.
- When a test fails, run the last failed test first using `uv run pytest --last-failed`.
- Use Test Driven Development (TDD) for all code you write. Write tests before writing the implementation code.
- When you come across a bug or regression, think hard about writing a test and also how to create code that will prevent this from a happening again in the future.
- Prefer testing real code where possible. Use mocks and `monkeypatch` when absolute necessary. Try to avoid mocking as much as possible.
Documentation¶
We use Google-style Docstrings in all functions and classes. We also typically write doctests to verify the documentation.
# Documentation
- Use google-style docstrings for all functions and classes you create.
- Include doctests in the docstrings of your functions to provide examples
Logging¶
We typically use Logging to gain insights into
errors. We do not want print statements in the code for debugging purposes.
However, we do not use logging to hide stack traces when an error occurs anyway.
Nor should Exceptions be hidden. If an
exception is to be caught, it should at least be logged.
# Logging
- Use logging to provide insight into failures. Don’t use print for debugging. Don’t use logging to hide stack traces if you are going to fail anyway.
- Don't hide exceptions. Let them propagate up to the caller. If you need to catch an exception, log it and re-raise it.
Command-line tools¶
With command-line tools, we usually want a –verbose flag that provides log
output useful for troubleshooting.
# Command line interface
- When creating a command line interface, add `--verbose` flag that provides logging output useful for debugging issues.