cookiecutter-uv-core is a Cookiecutter template for Python services managed with uv.
It generates a typed package in the src layout with layered configuration through
Pydantic, structured logging through structlog, asynchronous SQLAlchemy access to
PostgreSQL, a Click command-line interface, and multi-platform Docker images.
A Makefile drives dependency management, containerization, code quality checks, and tests. The generated project also carries instructions and skills for the Claude Code and OpenAI Codex coding agents.
Generating a project requires only uv, which runs Cookiecutter. Working with the generated project requires the following tools:
- GNU make;
- GNU sed, which
brew install gnu-sedinstalls on macOS; - Git;
- uv , preferably at the version that the
uv_versionprompt pins; - Docker Desktop on macOS, or Docker Engine with QEMU on Linux [1] .
ripgrep is optional. The Makefile uses it when it is installed, for example through
cargo install ripgrep.
make install installs the following tools as development dependencies of the
project:
| [1] | Simple multi-platform build using emulation with Docker . |
Environment
Run the following targets in the generated project to check the tools and to inspect the active configuration:
- Show the project version and the environment details:
make. - Check the primary tools:
make env-check. - Check the Git command and the work tree:
make env-check-git. - Check the Python requirements:
- the general requirements:
make env-check-python; - the project lockfile:
make env-check-lockfile; - the virtual environment:
make env-check-venv.
- the general requirements:
- the general requirements:
- Show the variables that configure Python and related tools:
make env-show-python. - Check the Docker requirements:
make env-check-docker. - Show the variables that configure Docker:
make env-show-docker. - Check the requirements of the quality assurance tools:
make env-check-qa. - Show the variables that configure the quality assurance tools:
make env-show-qa.
Run Cookiecutter through uvx, the tool runner of uv, which installs it into an
isolated environment on first use. From a local clone of this repository, run:
uvx cookiecutter --output-dir </path/to/dir> --overwrite-if-exists .
The . names the template in the current directory. Cookiecutter creates the project
inside the directory that --output-dir names, and -o is the short form of that
option. --overwrite-if-exists permits generating into a project directory that an
earlier run created.
To generate from the GitHub repository instead, replace . with a reference of the
form gh:<owner>/<repo>:
uvx cookiecutter -o </path/to/dir> gh:alexkey/cookiecutter-uv-core
The VERSION file holds the template version, and Changelog records the changes
of each release. Each release has a Git tag of the form v<version>. To generate from
a specific release, pass its tag to --checkout:
uvx cookiecutter -o </path/to/dir> --checkout v0.9.0 gh:alexkey/cookiecutter-uv-core
Cookiecutter prompts for the following values and shows the default of each. Press Enter to accept a default:
name- the project's display name, for exampleFooBar-baz. The valuesservice_name,repo_name, andenv_prefixderive from it.version- the initial project version.brief- a one-line package summary.description- a longer description for the generated README.author_nameandauthor_email- the author and maintainer details.urlandrepository- the URLs of the project homepage and the source repository.license- theSPDX license identifier .uv_versionandpython_version- the pinneduv and CPython versions. The generated code uses explicit lazy imports and therefore requires apython_versionof 3.15 or later.Changing the Python and uv Versions lists the files that pin them.docker_build_platform- the target platform of Docker image builds.redis_image_tagandpostgres_image_tag- the image tags of the Docker Compose services.postgres_user- the PostgreSQL user.
Cookiecutter derives the following values from the inputs above and prompts for them as well. Accept the derived defaults unless the project needs other values:
service_name- the lowercased project name.repo_name- the importable Python package name:service_namewith hyphens replaced by underscores.env_prefix- the prefix of the settings environment variables: the uppercased part ofnamebefore the first hyphen or underscore, followed by an underscore.python_majmin- the major and minor Python version.docker_compose_name- the Docker Compose project name.docker_prefix- the base path inside Docker images.year- the current year.
To generate a sample project with the defaults only, pass --no-input:
uvx cookiecutter -o </path/to/dir> --no-input .
The command creates the sample project foobar_baz, which serves for inspection and
experiments. uvx cookiecutter --help lists every Cookiecutter option.
Change into the directory of the generated project and continue with A Typical Session. Features lists the targets of the Makefile.
The following steps take the sample project foobar_baz from environment setup to a
running service.
Initialize a Git work tree, lock the dependencies, create the virtual environment, and install the project:
cd foobar_baz
git init
make requirements
make venv
make install
The make targets need no activated environment. Run any other command in the project
environment with the prefix uv run, as in uv run foobar-baz --help.
Alternatively, the project's venv helper activates the environment in the current
shell:
. ./venv
Check the formatting, run the analysis tools, and run the unit tests:
make check-format
make lint
make test
Build the image and start the service stack with Compose:
make docker-build
make docker-compose
make docker-compose runs in the foreground and removes the stack, volumes included,
on exit. Run the remaining commands from a second shell while the stack runs.
Point the database URL at the PostgreSQL port that Compose publishes on localhost.
Export it for the current shell:
export FOOBAR_DATABASE_URL="postgresql+asyncpg://database:database@localhost:5432/database"
Alternatively, set the same value in the project's .env.local file, which the
settings reads by default.
Run the system tests against the running database:
make autotest
Start the service, which logs its resolved configuration on startup:
uv run foobar-baz run
2026-06-28 16:50:46 [debug ] Settings(LOG_LEVEL='DEBUG', LOG_FORMAT='console', LOG_COLORS=True, LOG_VERBOSE=True, DATABASE_URL=SecretStr('**********')) [foobar_baz.app.cli._decorators] filename=_decorators.py func_name=wrapper lineno=57 process=76586 thread=140704445131008
2026-06-28 16:50:46 [info ] Welcome to foobar-baz version 0.1.0 [foobar_baz.app.cli._decorators] filename=_decorators.py func_name=wrapper lineno=59 process=76586 thread=140704445131008
...
Review the current state first:
make requirements-check
make requirements-try
make requirements-check lists the installed packages and marks the outdated ones,
transitive dependencies included. make requirements-try lists the outdated direct
dependencies and previews the upgrade that the constraints allow, without writing the
lockfile.
Raise the constraints of the outdated direct dependencies, then lock and install the upgrade:
make requirements-bump
make requirements-up
make requirements-bump rewrites only pyproject.toml. It raises the ~= and
>= clauses to the latest releases and preserves the rest of each requirement as
written. It reports a requirement whose other clauses would exclude the latest release
and leaves that requirement unchanged. Lock any pending pyproject.toml change first,
because the outdated versions come from the lockfile.
make requirements-up re-resolves every package, transitive dependencies included, to
the newest versions that the constraints allow, then installs them. Run
make requirements and make install instead to upgrade only the bumped
dependencies and keep the other locked versions.
Confirm the result, then run the checks and tests against the upgraded packages:
make requirements-check
make lint
make test
The python_version and uv_version prompts set the CPython and uv releases of
a new project, and cookiecutter.json holds their defaults. A generated project pins
each release in several files, and no pin follows another. Change every pin of a
release in one change. The following sections list the pins of each release.
Both releases meet in the base image tag of the Dockerfiles:
ghcr.io/astral-sh/uv:<uv_version>-python<major.minor>-trixie-slim
An image with this tag must exist for the new combination of releases. The uv
Docker guide lists the published tags. A generated project holds three identical
Dockerfiles: docker/Dockerfile.x86_64, docker/Dockerfile.arm64, and
docker/Dockerfile.aarch64. The Makefile selects one by the output of uname -m.
Edit the tag in all three files.
The generated code uses explicit lazy imports and therefore requires 3.15 or later.
Replace the lazy imports with regular imports and adapt the CLI startup tests in
tests/main/app/cli/test_cli.py before switching to an earlier release. Releases
before 3.14 also reject except A, B: without parentheses. Releases before 3.12 also
reject type parameter lists and type aliases.
A generated project pins the Python release in two forms.
The full version, such as 3.15.2:
.python-version, which holds only the version;requires-python = "~=3.15.2"inpyproject.toml;- the
requires-pythonline of the inline script metadata indocker/scripts/wait_for_pg.pyandetc/scripts/bump_requirements.py.
The major and minor version, such as 3.15:
- the
Programming Language :: Python :: 3.15classifier inpyproject.toml; - the
-python3.15-part of the base image tag in the three Dockerfiles; py-versioninpylintrc.
To change the Python release, edit every place in both lists. A patch release changes only the full version. Then lock the dependencies for the new release and recreate the environment:
make requirements
make install
make requirements re-resolves uv.lock for the new requires-python.
make install replaces a virtual environment whose interpreter differs from the new
release and installs the locked packages into the new environment. Rebuild the image
with make docker-build before the next container target. Finish with the checks and
tests:
make lint
make test
A generated project pins the uv release in its full version, such as 0.13.7:
UV_VERSIONin theMakefile;- the lower bound of the
uv_build>=0.13.7,<0.14requirement in the[build-system]table ofpyproject.toml; - the
0.13.7-prefix of the base image tag in the three Dockerfiles.
The upper bound of the uv_build requirement is the next minor release, such as
0.14 for 0.13.7. The template derives it from uv_version. A patch release
leaves the upper bound unchanged. A minor release raises it as well, such as to
<0.15 for 0.14.0.
UV_VERSION names the release that the host is expected to run.
make env-check-python prints a warning when the installed uv differs from it.
Every target that locks the dependencies, installs them, builds a distribution, or
runs the quality assurance tools runs this check first. A different release produces a
warning, not an error.
The uv_build requirement selects the build backend. The upper bound excludes the
next minor release, which can contain breaking changes. Without it, the source
distribution can fail to build once such a release is published, and uv warns about
the missing bound. uv builds the project with its bundled backend when its own
release satisfies the requirement. Otherwise, it downloads a uv_build package that
satisfies the requirement.
The image runs the uv release of its base image tag. That release must read the
uv.lock that the host writes. uv rejects a lockfile whose schema version is
newer than its own, and the schema version changes only in minor releases. Keep the
host and the image at the same release for that reason.
To change the uv release, edit every place in the list. Then install the same release on the host. A uv from the standalone installer updates itself to a given release:
uv self update 0.13.8
A uv from another installation method changes its release only through that method, such as its package manager. Confirm that the check no longer warns, then lock the dependencies and reinstall the project with the new release:
make env-check-python
make requirements
make install
Rebuild the image with make docker-build before the next container target. Finish
with the checks and tests:
make lint
make test
The generated project includes a Makefile whose targets are grouped by concern.
The following targets manage the virtual environment, the dependencies, and the package distributions:
- Create a virtual environment:
make venv. - Manage the dependencies and the lockfile:
- Update the lockfile:
make requirements. SetUV_LOCK_EXTRA_OPTSto--upgrade-package=<name>to upgrade one package. - Refresh all cached package data and update the lockfile:
make requirements-refresh. - List the outdated direct dependencies, then preview the upgrade without writing the
lockfile:
make requirements-try. - Raise the
~=and>=constraints of the outdated direct dependencies inpyproject.tomlto their latest versions:make requirements-bump. Then update the lockfile asUpdating the Dependencies describes. - Re-resolve every package to the newest versions that the constraints allow, and
install them:
make requirements-up. - List and validate the installed packages:
make requirements-check. - Display the dependency tree:
make requirements-tree.
- Update the lockfile:
- Update the lockfile:
- Synchronize the virtual environment with the lockfile:
make install. The target removes packages that the lockfile does not list. SetUV_SYNC_EXTRA_OPTSto:--all-extrasto include all optional dependencies;--inexactto keep packages that the lockfile does not list. SetINSTALL_EXTRASto a space-separated list of names to include selected optional dependencies.
- Reinstall all dependencies:
make force-install. - Build the source and wheel distributions:
make dist.
The following targets build images, run containers, and manage Docker resources:
- Show all images, containers, and volumes:
make docker-info. - Build an image from the Dockerfile:
make docker-build. SetDOCKER_EXTRA_OPTSto--progress=plainto show the full build output. - Create and run a container from the image, removed on exit:
make docker-run. SetDOCKER_EXTRA_OPTSto--publish 127.0.0.1:8000:8000to publish the container's port on the host. - Manage the service stack with Compose:
- Start the containers in the foreground, and remove them with their volumes on exit:
make docker-compose; - Follow the logs from the running containers:
make docker-logs; - Open a shell in the running service container:
make docker-shell. Build the image withmake docker-buildbefore the firstmake docker-compose, because the Compose file does not build it. To surface errors, warnings, and other problems in the log stream, filter it with ripgrep:
- Start the containers in the foreground, and remove them with their volumes on exit:
make docker-logs | rg -i "(err|crit|kill|garbage|warn)"
- Start the containers in the foreground, and remove them with their volumes on exit:
- Remove every container and image on the host, and prune unused networks, the build cache, and anonymous volumes:
make docker-clean. The target affects all Docker resources on the host, not only those of the project.
The following targets list source notes, analyze dependencies, and lint, format, and test the code:
- List the source notes with
NOTES_CONTEXTlines of surrounding context. Both targets require a Git work tree.- List all notes, sorted by tag:
make show-notes. - List the notes in the files of the last
GIT_DEPTHcommits and in modified files:make show-notes-recent.
- List all notes, sorted by tag:
- List all notes, sorted by tag:
- Find unused, missing, and transitive dependencies:
make check-deps. ConfigureDeptry in the[tool.deptry]section ofpyproject.toml. The target fails on a freshly generated project, becausepyproject.tomldeclares libraries that the shipped code does not import, such asFastAPI andCelery .Deptry reports each of them asDEP002. - Analyze the code:
- Lint with Ruff :
make check-ruff; - Perform static type checking with ty :
make check-ty; - Perform static type checking with Mypy :
make check-mypy; - Perform code analysis with Pylint :
make check-pylint; - Run all of the above analysis tools:
make lint. TheMYPY_OPTSandPYLINT_OPTSvariables and theruff.toml,ty.toml,mypy.ini,pytest.ini, andpylintrcfiles configure the quality assurance tools. The analysis and formatting targets checksrc,tests, andetc/scripts.The dependency, analysis, formatting, and test targets run their tools throughuv run --locked, at the versions inuv.lock. They require the virtual environment, the lockfile, and the installed tools.
- Lint with Ruff :
- Lint with
- Manage code formatting:
- Detect unformatted files:
make check-format; - Sort imports and format all Python files:
make format.
- Detect unformatted files:
- Detect unformatted files:
- Run tests:
- Run the unit tests in the
PYTEST_UNIT_DIRsubdirectory oftests:make test; - Run the system tests in the
PYTEST_SYSTEM_DIRsubdirectory oftests:make autotest.make autotestneeds a reachable database. It fails unless{{ cookiecutter.env_prefix }}DATABASE_URLis set and valid, orPYTEST_EXTRA_OPTSpasses--skip-db.Both targets acceptPYTEST_EXTRA_OPTSto forward extraPytest arguments andPYTEST_CUSTOM_PATHto restrict the run to specific paths.Testing describes these and further variables.
- Run the unit tests in the
- Run the unit tests in the
The following targets list the targets and remove generated files:
- View all available targets:
make help. - Remove the tool caches and bytecode:
make clean. - Remove the build and distribution output:
make distclean. - Run both cleanups, then delete the virtual environment and the entire uv cache,
which other projects share:
make mostlyclean.
The generated service rests on three runtime facilities: typed configuration, structured logging, and asynchronous database access. An application runtime and a Click command-line interface combine them into a runnable service.
The typed Pydantic model Settings holds the runtime configuration. A cached
accessor returns it:
from {{ cookiecutter.repo_name }} import get_settings
settings = get_settings()
- Each setting reads the environment variable that carries its name with the project's
prefix, for example
{{ cookiecutter.env_prefix }}LOG_LEVELand{{ cookiecutter.env_prefix }}DATABASE_URL. Names are case-sensitive. Environment variables that match no setting are ignored. - Values also come from an environment file, by default
.env.localin the working directory. Set{{ cookiecutter.env_prefix }}ENV_FILEto load another file. Process environment variables take precedence over the file. An entry in the file that matches no setting is rejected. The generated.env.localsets every setting, and the fields ofSettingsare the authoritative list. get_settings()returns a cached singleton. Passreload=Trueto discard the cache and rebuild the settings from the current environment.DATABASE_URLis required and validated. It must use thepostgresql+asyncpgdriver and include a database name and either a host or ahostquery parameter that names a socket directory. The settings hold it as aSecretStr, which stays masked when the settings are logged or printed.
Logging builds on structlog and formats records from structlog and from the standard library alike. Configure it once during startup from the settings above:
from {{ cookiecutter.repo_name }} import get_logger, get_settings, setup_logging
settings = get_settings()
setup_logging(
log_level=settings.LOG_LEVEL,
log_format=settings.LOG_FORMAT,
enable_colors=settings.LOG_COLORS,
)
logger = get_logger(__name__)
logger.info("service started")
- Call
setup_logging()once before the first log record. A later call reconfigures logging and replaces the handler that the previous call installed. log_formatselects the renderer:consolefor human-readable output andjsonfor machine-readable records, one object per line. Useconsoleinteractively andjsonin deployed environments. The console renderer formats tracebacks withRich , which can take seconds for a long traceback and blocks the thread that logs.log_levelsets the threshold below which records are dropped. Level names are case-insensitive.- Colors apply to
consoleoutput on a TTY only and are suppressed when theNO_COLORenvironment variable is set. - Create module-level loggers with
get_logger(__name__), and pass context as keyword arguments. Guard expensive log preparation withis_level_enabled(logger), which checks the debug level by default.
Database access uses asynchronous SQLAlchemy over the postgresql+asyncpg driver.
Helper functions cover the full lifecycle: creating and disposing the engine, building a
session factory, and opening sessions that commit or roll back automatically:
from {{ cookiecutter.repo_name }} import get_settings
from {{ cookiecutter.repo_name }}.app.db.database import (
create_engine,
create_session,
create_sessionmaker,
dispose_engine,
)
settings = get_settings()
engine = create_engine(settings.DATABASE_URL, raise_on_exc=True)
sessionmaker = create_sessionmaker(engine)
async with create_session(sessionmaker) as session:
await session.execute(...)
await dispose_engine(engine)
- Create the engine once with
create_engine(), and reuse it for the lifetime of the process, because it owns the connection pool. By default,create_engine()returnsNonewhen creation fails. Passraise_on_exc=Trueto fail fast at startup instead. Dispose the engine once during shutdown withawait dispose_engine(engine)to close the pooled connections. - Build a single session factory per engine with
create_sessionmaker(), and share it as the source of every session. Do not create an engine or a factory per request or per task. create_session()is an async context manager that opens one session and wraps the enclosed block in a single transaction. The transaction commits when the block exits cleanly and rolls back on any exception. The session is always closed. Use one block per unit of work, and let the block own the transaction boundary. Do not callsession.begin()orsession.commit()inside it.- With the default
raise_on_exc=True, database errors and unexpected errors are re-raised after the rollback.asyncio.CancelledErroralways rolls back and propagates. Passcontext=...to label a session in log records, andverbose=Trueto log each lifecycle step.
- With the default
- With the default
- The defaults for the engine and the sessions live in
DEFAULT_ASYNC_ENGINE_PARAMSandDEFAULT_ASYNC_SESSION_PARAMS. Read the active values there, and override any of them through keyword arguments tocreate_engine()andcreate_sessionmaker().- Sessions set
expire_on_commit=False. With theSQLAlchemy default ofTrue,commit()expires the attributes, and the first later access to each attribute triggers an implicit refresh SELECT. Under asyncio, that implicit I/O can run outsideSQLAlchemy 's async bridge and raiseMissingGreenlet. The tradeoff is that objects are not re-fetched after a commit.A server-generated value fromserver_default,server_onupdate, orComputedis available only whenSQLAlchemy populated it during the flush, typically throughRETURNING. A value that was not populated stays expired, and accessing it triggers the same implicit I/O. A value thatSQLAlchemy does not know to be computed on the server can stay stale in memory. Fetch such values explicitly withawait session.refresh(obj, [...]), and load relationships eagerly withselectinload()instead of relying on attribute access. - The pool settings work together when connections pass through intermediaries.
pool_pre_pingchecks a connection when it leaves the pool and replaces one that was dropped while idle.pool_use_lifokeeps traffic on a small set of connections, which lets the surplus connections idle out on the server during quiet periods.pool_recyclelimits the connection age to 1800 seconds. Keep it below the shortest idle timeout of any component in the network path, such as a load balancer, NAT, or a connection pooler. An AWS Network Load Balancer closes idle TCP connections after 350 seconds by default, which calls for a value such as 300 seconds. PgBouncer closes idle client connections only whenclient_idle_timeoutis set, and that timeout is disabled by default.pool_pre_pingdetects stale connections when they leave the pool, andpool_recyclekeeps connections from reaching that state.
- Sessions set
The service is a Click command-line program. An application lifespan provides the shared resources that each command needs while it runs.
Two entry points launch the service: the console script
{{ cookiecutter.service_name }} and python -m {{ cookiecutter.repo_name }}. The
[project.scripts] table of pyproject.toml declares the console script. Both call
main(), which hands control to the Click group cli. The group parses the
arguments and dispatches to a subcommand.
The application lifespan owns the shared resources, not the individual commands.
app_lifespan() is an async context manager that wraps a command body and holds the
resources for its duration:
- On entry, it creates the database engine and the session factory, and yields a shared
AppState. - On exit, it disposes the engine whether the body returned or raised. The pooled connections are therefore released on every path.
AppStateis a typed mapping of the resources that the lifespan provides to the command body. It carries the session factory. Further resources owned by the lifespan extend it.- When the engine cannot be created, the lifespan fails fast and exits with
EXIT_GENERAL_ERRORinstead of yielding a partially initialized state.
The lifespan follows the database guidance above: it creates the engine and the session factory once and disposes them once. A command opens sessions from the supplied factory and never manages the engine itself.
The template ships one subcommand, run, whose body is a stub. It enters the lifespan
and leaves a placeholder for the service's own logic. Further behavior goes into more
subcommands. Two mechanisms keep startup cheap:
LazyGroupimports a subcommand's module only when that command is resolved. Invoking one command never imports another.- Explicit lazy imports defer each module's dependencies until their first use. PEP 810
added them in Python 3.15. The group's
--helpimports every command module to show its short help, but those modules load none of their dependencies until a command body runs. As a result,--helpand--versionload nothing beyond the standard library andClick .
Creating a command therefore takes two steps. First, place a module that exposes a
click.Command under app/cli/commands/, and import with lazy everything that
only the command body uses. For example, app/cli/commands/healthcheck.py reuses the
lifespan and the decorators below:
import click
from {{ cookiecutter.repo_name }}.app.cli._decorators import (
announce,
configure,
run_async,
)
lazy from {{ cookiecutter.repo_name }}.app.runtime import app_lifespan
@click.command("healthcheck", help="Verify the database connection.")
@configure
@announce
@run_async
async def healthcheck_cmd() -> None:
async with app_lifespan() as app_state:
session_maker = app_state["session_maker"]
...
Second, register the command object with one entry in the _SUBCOMMANDS mapping in
app/cli/__init__.py. The key is the command name, and the value is the dotted path
of the object:
_SUBCOMMANDS = MappingProxyType(
{
"run": "{{ cookiecutter.repo_name }}.app.cli.commands.run.run_cmd",
"healthcheck": "{{ cookiecutter.repo_name }}.app.cli.commands.healthcheck.healthcheck_cmd",
}
)
The group verifies that the entry names a click.Command when it loads the entry. The
module is imported when the group's help is shown or when
{{ cookiecutter.service_name }} healthcheck runs. Its dependencies are imported only
when the command runs. A unit test fails when the group's --help or --version
loads a third-party package other than Click. The test thereby detects an import on
the startup path that lacks the lazy keyword.
Three decorators factor out the setup that every command shares. They stack beneath
@click.command in a fixed order, as the example above shows:
configureresolves the settings and configures logging before the body runs. Logging therefore uses the effective configuration from the first record.announcelogs the resolved settings at debug level and then a version banner at info level. The debug record sits behind the level guard thatLogging (logging.py) recommends.run_asyncadapts anasync defbody to the synchronous callback thatClick expects, and drives the body to completion withasyncio.run().
Decorators wrap from the bottom up but execute from the top down. Logging is therefore
configured first, the startup announcement follows, and the asynchronous body runs last.
The body enters app_lifespan() to acquire the shared resources for the lifetime of
the command.
Tests run under Pytest. make test runs the unit tests, and make autotest runs
the system tests:
make test
make autotest
make autotest reserves PYTEST_DEPLOYMENT for the URL of a deployed service that
system tests target. The default is http://localhost:8000. The target prints the
value, and the shipped system tests do not read it.
The shared tests/conftest.py registers two markers, slow and requires_db.
Test code applies them as @pytest.mark.slow and @pytest.mark.requires_db. Each
marker has an option that skips the tests that carry it:
slowmarks tests that are expensive to run. Pass--skip-slowto skip them. The option has no effect until a test carries this marker.requires_dbmarks tests that need a live database. Pass--skip-dbto skip them. Only the tests intests/systemcarry this marker. As a result,--skip-dbaffects onlymake autotest.
The two options are independent and can be combined, for example
PYTEST_EXTRA_OPTS="--skip-slow --skip-db".
The following Makefile variables customize a test run:
PYTEST_EXTRA_OPTSforwards extra arguments toPytest , such as the skip options above or any otherPytest flag.PYTEST_CUSTOM_PATHselects a path under the target's test directory, down to an individual module, class, or test. The test directory istests/mainformake testandtests/systemformake autotest.PYTEST_DURATIONSsets how many of the slowest tests the run reports, through thePytest option--durations. The default is10.PYTEST_LOG_CLIenablesPytest 's live logging, which streams each log record to the console as the run proceeds. The default isfalse.PYTEST_LOG_CLI_LEVELsets the threshold of live logging, by defaultINFO. Live records render throughPytest 's own formatter as a raw dict, not in the application's JSON or console format. A traceback appears only forlog.exception()records.PYTEST_CAPTUREselectsPytest 's output capture mode, through the option--capture. The default isfd, ornowhenPYTEST_LOG_CLI=true.
For example:
make test PYTEST_CUSTOM_PATH=<subdir>
make test PYTEST_CUSTOM_PATH=<path/to/module.py>::<TestClass>::<test_method>
make test PYTEST_EXTRA_OPTS=--skip-slow
make autotest PYTEST_EXTRA_OPTS=--skip-db
make test \
PYTEST_CUSTOM_PATH=app/core/test_config.py::TestGetSettings::test_reload_picks_up_changed_environment \
PYTEST_EXTRA_OPTS=--count=10
The suite shares the following helpers, importable as
from tests.utils import <func>:
fail_without_traceback(reason)fails the current test and reports onlyreason, with no traceback. Use it for unmet external prerequisites, where a traceback adds no information.parse_json_lines(stream)parses a captured JSON-logStringIOinto a list of records, onedictper line, and skips blank lines.assert_log_event(stream, match, *, count=1, **fields)asserts that exactlycountcaptured records containmatchas a substring of theirevent. Every match must also contain each**fieldspair, for examplelevel="error". The helper returns the matches for further inspection.assert_log_exception(stream, match, exc_type, *, exc_value=None, level="error")asserts that a single matching record logged an exception ofexc_type. It searches the whole structuredexceptionchain and optionally checksexc_value. Prefer it to indexingrecord["exception"]by hand, because it does not depend on the position of the exception in the chain._database_url(...)builds a database URL from individual components. Each component defaults to a module-level constant:_DRIVER,_USER,_PASSWORD,_HOST,_PORT, or_DATABASE.VALID_DATABASE_URLis the URL with all defaults. These values back thedatabase_*fixtures below.
Fixtures are defined in conftest.py files and apply to every test at or below their
directory. pytest.ini runs pytest-asyncio in auto mode. As a result, async tests
need no @pytest.mark.asyncio marker, and async fixtures use the plain
@pytest.fixture decorator.
tests/conftest.py serves the whole suite:
rng- a session-scoped, seededrandom.Random. The test header shows the seed, and{{ cookiecutter.env_prefix }}TEST_SEEDpins it. This file also registers theslowandrequires_dbmarkers above.
tests/main/conftest.py serves the unit tests that make test runs:
reset_logging_state- automatic. It snapshots and restores the process-wide logging state around every test, which keeps one test's logging configuration from leaking into the next._isolate_settings- automatic. Around every test, it removes the environment variable of eachSettingsfield and{{ cookiecutter.env_prefix }}ENV_FILE, and it clears the cached settings. It derives the variable names from the fields ofSettings, which lets a new setting work without a fixture change..env.localstays readable.valid_environment- supplies a valid database URL and replaces.env.localwith an empty environment file. Request it in a test that needs valid settings independent of the developer's.env.local.cap_json_logs- configures JSON logging to aStringIOand yields it. Read it with the helpers oftests/utils.pyabove.make_fake_stream- a factory for a fake stream with a configurableisatty(), which exercises the color and TTY decisions.database_driver,database_user,database_password,database_host,database_port, anddatabase_name- the individual URL components.make_database_urlis the URL factory, andvalid_database_urlis the URL with all defaults. Assert against these fixtures instead of hard-coded URL strings.
tests/main/app/db/conftest.py serves the database unit tests:
make_fake_sessionmaker- returns theFakeSessionMakerclass. Pass an instance tocreate_session()in place of a real session factory. Itssessionattribute holds aFakeSessionwhosetransactionis aFakeTransaction. Inspect them to assert commit or rollback without a live database.
tests/system/conftest.py serves the system tests that make autotest runs:
app_logging- session-scoped and automatic. It configures logging as the application does, which keeps local variables out of logged tracebacks.database_url- session-scoped. It resolves the real database URL from{{ cookiecutter.env_prefix }}DATABASE_URLand fails the suite when the URL is unset or invalid, or the database is unreachable. Pass--skip-dbto skip the suite instead. The URL is aSecretStr, which keeps the password masked in the function arguments thatPytest prints in tracebacks. Callget_secret_value()only where a plain string is required. The masking does not extend to the frames ofSQLAlchemy and the database driver. Do not pass--tb=long,--full-trace, or--showlocalswhere logs are shared.database_schema- session-scoped. It creates a dedicateditest_<random>schema for the run and drops it withCASCADEafterward.database_engineanddatabase_sessionmaker- a real engine bound to the configured database, disposed after each test, and a session factory bound to that engine.items_table- creates an isolated table in the run schema and drops it after the test.
The generated project is prepared for the coding agents Claude Code and OpenAI Codex. Both agents load its project instructions at the start of every session. They load one of its agent skills when a task calls for it or when the user invokes the skill by name.
Each asset has one canonical copy, stored where Codex reads it. A post-generation hook symlinks it into the location that Claude Code reads. Edit only the canonical copy:
| Asset | Canonical copy ( Codex ) | Symlink ( Claude Code ) |
|---|---|---|
| Project instructions | AGENTS.md |
CLAUDE.md |
| General instructions | AGENTS.override.md |
CLAUDE.local.md |
| Reference files | .agents/docs/<topic>.md |
none; read on demand |
| Agent skills | .agents/skills/<name>/ |
.claude/skills/<name> |
The symlinks are relative and belong under version control with the rest of the project.
AGENTS.md in the project root gives an agent the knowledge that it cannot infer from
the code: the mandatory rules, the commands of the development workflow, the project
layout, and an index of reference files. Codex reads AGENTS.md natively, as
Custom instructions with AGENTS.md describes. Claude Code reads the symlink
CLAUDE.md, as How Claude remembers your project describes. From v2.1.277, Claude
Code also reads AGENTS.md directly, but by default only when no CLAUDE.md or
CLAUDE.local.md exists in the working directory or above it. The generated project
contains CLAUDE.local.md, and Claude Code therefore depends on the symlink.
AGENTS.override.md in the project root holds general instructions that do not depend
on the project: output formatting, technical writing, documentation lookups for external
libraries, the use of uv, and code comments. Claude Code reads it through the
symlink CLAUDE.local.md and places it after CLAUDE.md. Codex reads at most one
instruction file per directory and prefers AGENTS.override.md to AGENTS.md. The
first instruction in AGENTS.override.md therefore directs Codex to read
AGENTS.md. Codex receives the project instructions through that file read, not
through automatic .
Cookiecutter renders the instruction files. They therefore name the package, the console script, and the environment prefix of the generated project.
Organization
The instructions keep the context that every session pays for small:
AGENTS.mdis loaded into every session and holds only what applies to most tasks.AGENTS.override.mdis loaded into every session as well and holds only rules that apply to any project.- The reference files under
.agents/docsare not loaded automatically. TheReference table inAGENTS.mdnames the tasks that each file serves, and the agent reads a file when its task enters that area:architecture.md- components, startup flow, design decisions, configuration, logging, and recipes for adding a command, a setting, or a shared resource;database.md- session and engine lifecycle, and the rationale behind the defaults;conventions.md- code conventions that the analysis tools do not enforce on their own;testing.md- test layout, running tests, fixtures, and helpers;workflows.md- environment setup, quality checks, dependency management, builds, and execution plans;infrastructure.md- the Docker image, the Compose stack, and their targets.
- Sections titled Rules are mandatory for the agent. All other content is context that informs its decisions. Where that context disagrees with the code, the code wins, and the instructions are corrected.
Verification
Start the agent in the root of the generated project and confirm that it loaded the instructions:
- In Claude Code , run
/context all.CLAUDE.mdandCLAUDE.local.mdappear in the list underMemory files ./memorydoes not confirm , because it also lists the locations of files that do not exist. - In Codex , run
codex "Summarize the current instructions.". The summary cites the rules from bothAGENTS.override.mdandAGENTS.md. A summary that cites onlyAGENTS.override.mdmeans thatCodex did not follow the instruction to readAGENTS.md.
Codex loads instruction files from the project root down to the working directory, and it typically takes the Git root as the project root. Initialize the Git work tree first to make the generated project that root, as A Typical Session shows.
Maintenance
- Edit
AGENTS.mdandAGENTS.override.md, neverCLAUDE.mdorCLAUDE.local.md.Claude Code refuses to write through the symlinks. - Keep the instruction at the top of
AGENTS.override.mdthat directs the agent to readAGENTS.md. Without it,Codex does not see the project instructions. - Update the instructions in the same change that alters a command, a path, a rule, or a design decision they describe. Delete an instruction that the code no longer supports.
- Keep
AGENTS.mdunder 200 lines, becauseClaude Code recommends that size for reliable adherence. The limit also keeps the file well within the 32 KiB thatCodex reads from project instruction files by default. Move detail that serves one area into a reference file, and list that file in theReference table. - The template occupies
CLAUDE.local.mdandAGENTS.override.md. The agents otherwise leave these file names to the user for personal or temporary project instructions. Keep such instructions in the user-level files instead:~/.claude/CLAUDE.mdforClaude Code and~/.codex/AGENTS.mdforCodex . - In the template, the instruction files are Jinja templates. Cookiecutter copies the
skills without rendering them. Use the
cookiecutter.*variables in the instruction files for project-specific names, and keep literal Jinja delimiters out of their text.
The bundled skills use the open Agent Skills format and run unchanged in
Claude Code and OpenAI Codex. Codex reads the canonical copy of each skill in
.agents/skills/<name>. The post-generation hook symlinks it into .claude/skills,
which Claude Code reads.
Bundled Skills
Overview
The update-tests skill creates new tests and improves existing ones at any test
level. It assumes no language, framework, or layout, and learns the tooling,
conventions, and test infrastructure from the project. Do not use it to debug a
production defect behind a single failing test.
Usage
Start the agent in the project root and invoke the skill with a mode, a path, and optional instructions:
<create|update> <path> [instructions]
In Claude Code, type /update-tests followed by the arguments. In Codex, mention
$update-tests in the message. Both agents also select the skill on their own when a
request asks to write, review, refactor, or stabilize tests. The request then supplies
the arguments.
For example:
/update-tests create tests/main/app/cli cover lazy subcommand
/update-tests create tests/main/app/test_runtime.py cover app_lifespan
/update-tests update tests/main/app/core
$update-tests update tests/main/test_logging.py focus on order dependence
The skill restates the resolved arguments, presents a plan before editing, and ends with a report of its changes and how it verified them. It asks before it starts a service that the tests need, such as PostgreSQL for the system tests, and starts the service only through the project's own means. It stops the services it started before it finishes, and it leaves services that were already running untouched.
Arguments
mode(required) -createorupdate:createwrites new tests atpathfor the code or behavior that the instructions name;updateaudits the tests atpathand refactors them to close coverage gaps, remove redundancy, strengthen weak assertions, and eliminate flakiness. When the first word is not a mode, the skill infers the mode from the request. It asks when the request supports both readings.
path(required) - one directory or test file, relative to the working directory. It is the only location where the skill creates or changes tests. Changes to anything else, such as production code, shared fixtures, or dependencies, are proposed and applied only after approval. Inupdatemode, the path must contain tests. Increatemode, it may name a directory or file that does not exist yet, provided that its parent directory exists. Without a path, the skill asks for one instead of searching the project.instructions(optional) - free text after the path. Increatemode, it names the code or behavior to test. Without instructions, the skill extends the existing tests atpath, and it asks what to test when there are none. Inupdatemode, the instructions narrow or direct the work, for example toward a specific problem. They can also extend the work to code that no test atpathexercises. Without such instructions, the skill lists that code as a follow-up, with thecreateinvocation that would cover it.
Overview
The develop skill carries a substantial change from requirements to working,
documented code in three stages: planning, implementation, and optional testing. Each
stage starts only on the user's explicit approval. The skill suits new projects, new
features, ports from another codebase, language, or platform, imports of external
functionality, reimplementations, and integrations between existing systems. Like
update-tests, it assumes no language, framework, or layout and learns them from the
project. Do not use it to fix a single defect, make a small edit, refactor without
changing behavior, or work only on tests.
Usage
Start the agent in the project root and invoke the skill with an optional plan path and a task:
[plan-path] <task>
In Claude Code, type /develop followed by the arguments. In Codex, mention
$develop in the message. The skill runs only when invoked by name. The agents do not
select it on their own, and an ordinary request does not start the staged process.
For example:
/develop add a migrate command that applies database schema migrations
/develop port the retry policy of ../legacy-worker into the runtime
/develop docs/exec-plans/active/2026-11-12-health.md add a health command
/develop docs/exec-plans/active/2026-11-12-health.md
$develop integrate the Redis cache from the Compose stack into the runtime
The skill restates the task, the plan location, and the starting stage before doing any work, and ends each stage with a report.
Stages and approval
- Planning. The skill studies the project, pins down the requirements, and designs the change. It uses a planning skill and the agent's plan mode when they are available. The default planning skill isbrainstorm . The stage ends with an execution plan, and nothing in the project changes before the plan is approved.
- Implementation. After approval, the skill saves the plan, records a baseline of the checks and tests, and implements the plan milestone by milestone, keeping the plan current. A significant deviation, such as a changed requirement, interface, or dependency, waits for approval. Existing tests that an approved behavior change invalidates are updated in this stage, without weakening the coverage of unchanged behavior. New tests are not written. The stage ends with a report and the question whether to proceed with testing.
- Testing (optional). The skill creates or updates the tests through
update-testsonly when the user agrees, with one full invocation per approved target. The user may approve all proposed targets or a subset. The targets declined or left out are recorded as follow-ups in the plan and the tech-debt tracker.
Approval is never implied. Silence, a question, or a saved plan status does not count. A plan resumed in a new session is presented for approval again, as is a plan changed in substance since its approval. The skill stops after planning in a non-interactive run. It then saves the draft plan where writes are permitted, and otherwise returns the plan in its final message.
Arguments
plan-path(optional) - the execution plan, relative to the working directory. An existing plan is resumed. A path that does not exist yet names the new plan file. The skill asks before using a path whose parent directory is missing, and it points out a location outsidedocs/exec-plans/before approval. Without a plan path, the plan goes todocs/exec-plans/active/.task- free text that states the goal or points to the requirements, such as a specification, an issue, or the code to port. It may be omitted when the plan path resumes a plan.
Execution plans
Plans follow OpenAI's ExecPlans methodology. Each plan is a living, self-contained document from which a later session can finish the work. It holds a progress log, a record of discoveries, a decision log, and a retrospective. The skill keeps the plans in the layout that Harness engineering describes:
docs/exec-plans/
active/ plans in progress
completed/ completed and cancelled plans
tech-debt-tracker.md deferred work and known shortcuts
A plan's file name is its creation date in ISO 8601 form followed by a short kebab-case
description, such as 2026-11-12-health-command.md. Every date and time in the plans
and the tracker is in UTC. A small change without design decisions gets a lightweight
plan. That plan needs approval like any other, but the skill saves it only when a plan
path is given. Project guidance in a file such as AGENTS.md may prescribe another
location than docs/exec-plans/.
Development standards
The skill holds the implementation to built-in standards for completeness, correctness
and reliability, security, simplicity, maintainability, testability, and documentation.
It checks them itself before it reports the implementation as complete. The standards
turn review criteria into development rules: requirements traced to code and wired end
to end, errors and resources handled on every path, input validated and secrets kept out
of code and logs, the direct solution preferred over speculative abstraction, and user
documentation, agent instructions, and the plan updated in the same change. Test quality
remains the responsibility of update-tests.