cd /news/ai-agents/show-hn-cookiecutter-uv-core-uv-temp… · home › topics › ai-agents › article
[ARTICLE · art-170768] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Show HN: Cookiecutter-uv-core – uv template with an agent SDLC and quality gates

A developer released cookiecutter-uv-core, a Cookiecutter template that generates a typed Python service package managed with uv, including Pydantic configuration, structlog logging, asynchronous SQLAlchemy access to PostgreSQL, a Click command-line interface, and multi-platform Docker images. The generated project ships instructions and skills for the Claude Code and OpenAI Codex coding agents, and a Makefile drives dependency management, containerization, quality checks, and tests, with environment targets such as make env-check and make env-check-qa. Generating a project requires only uv, which runs Cookiecutter via uvx, and releases are tagged as v<version>, with v0.9.0 cited as an example checkout.

read38 min views5 publishedNov 16, 2026
Show HN: Cookiecutter-uv-core – uv template with an agent SDLC and quality gates
Image: Michielbdejong (auto-discovered)

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-sed installs on macOS;
  • Git;
  • uv , preferably at the version that theuv_version prompt 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:
  • 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_prefix derive from it.
  • version - the initial project version.
  • brief - a one-line package summary.
  • description - a longer description for the generated README.
  • author_name andauthor_email - the author and maintainer details.
  • url andrepository - the URLs of the project homepage and the source repository.
  • license - theSPDX license identifier .
  • uv_version andpython_version - the pinneduv and CPython versions. The generated code uses explicit lazy imports and therefore requires apython_version of 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_tag andpostgres_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_name with hyphens replaced by underscores.
  • env_prefix - the prefix of the settings environment variables: the uppercased part ofname before 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-python line of the inline script metadata indocker/scripts/wait_for_pg.py andetc/scripts/bump_requirements.py .

The major and minor version, such as 3.15:

  • the Programming Language :: Python :: 3.15 classifier inpyproject.toml ;
  • the -python3.15- part of the base image tag in the three Dockerfiles;
  • py-version inpylintrc .

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_VERSION in theMakefile ;
  • the lower bound of the uv_build>=0.13.7,<0.14 requirement 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_OPTS to--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.toml to 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:
  • Synchronize the virtual environment with the lockfile: make install . The target removes packages that the lockfile does not list. SetUV_SYNC_EXTRA_OPTS to:
    • --all-extras to include all optional dependencies;
    • --inexact to keep packages that the lockfile does not list. Set INSTALL_EXTRAS to 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_OPTS to--progress=plain to show the full build output.
  • Create and run a container from the image, removed on exit: make docker-run . SetDOCKER_EXTRA_OPTS to--publish 127.0.0.1:8000:8000 to 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 with make docker-build before 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:
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_CONTEXT lines 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_DEPTH commits and in modified files:make show-notes-recent .
  • 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.toml declares 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 . The MYPY_OPTS andPYLINT_OPTS variables and theruff.toml ,ty.toml ,mypy.ini ,pytest.ini , andpylintrc files configure the quality assurance tools. The analysis and formatting targets checksrc ,tests , andetc/scripts .The dependency, analysis, formatting, and test targets run their tools through uv run --locked , at the versions inuv.lock . They require the virtual environment, the lockfile, and the installed tools.
  • Lint with
  • Manage code formatting:
    • Detect unformatted files: make check-format ;
    • Sort imports and format all Python files: make format .
  • Detect unformatted files:
  • Run tests:
    • Run the unit tests in the PYTEST_UNIT_DIR subdirectory oftests :make test ;
    • Run the system tests in the PYTEST_SYSTEM_DIR subdirectory oftests :make autotest . make autotest needs a reachable database. It fails unless{{ cookiecutter.env_prefix }}DATABASE_URL is set and valid, orPYTEST_EXTRA_OPTS passes--skip-db .Both targets accept PYTEST_EXTRA_OPTS to forward extraPytest arguments andPYTEST_CUSTOM_PATH to restrict the run to specific paths.Testing describes these and further variables.
  • 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_LEVEL and{{ 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.local in the working directory. Set{{ cookiecutter.env_prefix }}ENV_FILE to 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.local sets every setting, and the fields ofSettings are the authoritative list.
  • get_settings() returns a cached singleton. Passreload=True to discard the cache and rebuild the settings from the current environment.
  • DATABASE_URL is required and validated. It must use thepostgresql+asyncpg driver and include a database name and either a host or ahost query 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_format selects the renderer:console for human-readable output andjson for machine-readable records, one object per line. Useconsole interactively andjson in deployed environments. The console renderer formats tracebacks withRich , which can take seconds for a long traceback and blocks the thread that logs.
  • log_level sets the threshold below which records are dropped. Level names are case-insensitive.
  • Colors apply to console output on a TTY only and are suppressed when theNO_COLOR environment 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() returnsNone when creation fails. Passraise_on_exc=True to 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.CancelledError always rolls back and propagates. Passcontext=... to label a session in log records, andverbose=True to log each lifecycle step.
  • With the default
  • The defaults for the engine and the sessions live inDEFAULT_ASYNC_ENGINE_PARAMS andDEFAULT_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 from server_default ,server_onupdate , orComputed is 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_ping checks a connection when it leaves the pool and replaces one that was dropped while idle.pool_use_lifo keeps traffic on a small set of connections, which lets the surplus connections idle out on the server during quiet periods.pool_recycle limits 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_timeout is set, and that timeout is disabled by default.pool_pre_ping detects stale connections when they leave the pool, andpool_recycle keeps connections from reaching that state.

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.
  • AppState is 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_ERROR instead 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:

  • LazyGroup imports 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 --help imports every command module to show its short help, but those modules load none of their dependencies until a command body runs. As a result,--help and--version load 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:

  • configure resolves the settings and configures logging before the body runs. Logging therefore uses the effective configuration from the first record.
  • announce logs 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_async adapts anasync def body 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:

  • slow marks tests that are expensive to run. Pass--skip-slow to skip them. The option has no effect until a test carries this marker.
  • requires_db marks tests that need a live database. Pass--skip-db to skip them. Only the tests intests/system carry this marker. As a result,--skip-db affects 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_OPTS forwards extra arguments toPytest , such as the skip options above or any otherPytest flag.
  • PYTEST_CUSTOM_PATH selects a path under the target's test directory, down to an individual module, class, or test. The test directory istests/main formake test andtests/system formake autotest .
  • PYTEST_DURATIONS sets how many of the slowest tests the run reports, through thePytest option--durations . The default is10 .
  • PYTEST_LOG_CLI enablesPytest 's live logging, which streams each log record to the console as the run proceeds. The default isfalse .PYTEST_LOG_CLI_LEVEL sets 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_CAPTURE selectsPytest 's output capture mode, through the option--capture . The default isfd , orno whenPYTEST_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-logStringIO into a list of records, onedict per line, and skips blank lines.
  • assert_log_event(stream, match, *, count=1, **fields) asserts that exactlycount captured records containmatch as a substring of theirevent . Every match must also contain each**fields pair, 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 structuredexception chain 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_URL is 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_SEED pins it. This file also registers theslow andrequires_db markers 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 eachSettings field 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.local stays readable.
  • valid_environment - supplies a valid database URL and replaces.env.local with 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 aStringIO and yields it. Read it with the helpers oftests/utils.py above.
  • 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_url is the URL factory, andvalid_database_url is 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 theFakeSessionMaker class. Pass an instance tocreate_session() in place of a real session factory. Itssession attribute holds aFakeSession whosetransaction is 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_URL and fails the suite when the URL is unset or invalid, or the database is unreachable. Pass--skip-db to 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--showlocals where logs are shared.
  • database_schema - session-scoped. It creates a dedicateditest_<random> schema for the run and drops it withCASCADE afterward.
  • database_engine anddatabase_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.md is loaded into every session and holds only what applies to most tasks.
  • AGENTS.override.md is loaded into every session as well and holds only rules that apply to any project.
  • The reference files under .agents/docs are not loaded automatically. TheReference table inAGENTS.md names 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.md andCLAUDE.local.md appear in the list underMemory files ./memory does not confirm , because it also lists the locations of files that do not exist.
  • In Codex , runcodex "Summarize the current instructions." . The summary cites the rules from bothAGENTS.override.md andAGENTS.md . A summary that cites onlyAGENTS.override.md means 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.md andAGENTS.override.md , neverCLAUDE.md orCLAUDE.local.md .Claude Code refuses to write through the symlinks.
  • Keep the instruction at the top of AGENTS.override.md that 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.md under 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.md andAGENTS.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.md forClaude Code and~/.codex/AGENTS.md forCodex .
  • 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) -create orupdate :
    • create writes new tests atpath for the code or behavior that the instructions name;
    • update audits the tests atpath and 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. Inupdate mode, the path must contain tests. Increate mode, 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. Increate mode, 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. Inupdate mode, the instructions narrow or direct the work, for example toward a specific problem. They can also extend the work to code that no test atpath exercises. Without such instructions, the skill lists that code as a follow-up, with thecreate invocation 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

  1. 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.
  2. 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.
  3. Testing (optional). The skill creates or updates the tests throughupdate-tests only 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.

── more in #ai-agents 4 stories · sorted by recency
── more on @cookiecutter-uv-core 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/show-hn-cookiecutter…] indexed:0 read:38min 2026-11-16 · —