{"slug": "show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates", "title": "Show HN: Cookiecutter-uv-core – uv template with an agent SDLC and quality gates", "summary": "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.", "body_md": "*cookiecutter-uv-core* is a [Cookiecutter](https://cookiecutter.readthedocs.io/) template for Python services managed with [uv](https://docs.astral.sh/uv/).\nIt generates a typed package in the `src` layout with layered configuration through\n*Pydantic*, structured logging through *structlog*, asynchronous *SQLAlchemy* access to\nPostgreSQL, a *Click* command-line interface, and multi-platform Docker images.\n\nA Makefile drives dependency management, containerization, code quality checks, and\ntests. The generated project also carries instructions and skills for the *Claude Code*\nand *OpenAI Codex* coding agents.\n\nGenerating a project requires only *uv*, which runs Cookiecutter. Working with the\ngenerated project requires the following tools:\n\n- GNU make;\n- GNU sed, which `brew install gnu-sed` installs on macOS;\n- Git;\n- *uv* , preferably at the version that the`uv_version` prompt pins;\n- Docker Desktop on macOS, or Docker Engine with QEMU on Linux [\\[1\\]](#docker) .\n\nripgrep is optional. The Makefile uses it when it is installed, for example through\n`cargo install ripgrep`.\n\n`make install` installs the following tools as development dependencies of the\nproject:\n\n| [\\[1\\]](#id1) | [Simple multi-platform build using emulation with Docker](https://docs.docker.com/build/building/multi-platform/#simple-multi-platform-build-using-emulation) . | \n\n**Environment**\n\nRun the following targets in the generated project to check the tools and to inspect the active configuration:\n\n- Show the project version and the environment details: `make` .\n- Check the primary tools: `make env-check` .\n- Check the Git command and the work tree: `make env-check-git` .\n- Check the Python requirements:\n  - the general requirements: `make env-check-python` ;\n  - the project lockfile: `make env-check-lockfile` ;\n  - the virtual environment: `make env-check-venv` .\n- the general requirements: \n- Show the variables that configure Python and related tools: `make env-show-python` .\n- Check the Docker requirements: `make env-check-docker` .\n- Show the variables that configure Docker: `make env-show-docker` .\n- Check the requirements of the quality assurance tools: `make env-check-qa` .\n- Show the variables that configure the quality assurance tools: `make env-show-qa` .\n\nRun Cookiecutter through `uvx`, the tool runner of *uv*, which installs it into an\nisolated environment on first use. From a local clone of this repository, run:\n\n```\nuvx cookiecutter --output-dir </path/to/dir> --overwrite-if-exists .\n```\n\nThe `.` names the template in the current directory. Cookiecutter creates the project\ninside the directory that `--output-dir` names, and `-o` is the short form of that\noption. `--overwrite-if-exists` permits generating into a project directory that an\nearlier run created.\n\nTo generate from the GitHub repository instead, replace `.` with a reference of the\nform `gh:<owner>/<repo>`:\n\n```\nuvx cookiecutter -o </path/to/dir> gh:alexkey/cookiecutter-uv-core\n```\n\nThe `VERSION` file holds the template version, and `Changelog` records the changes\nof each release. Each release has a Git tag of the form `v<version>`. To generate from\na specific release, pass its tag to `--checkout`:\n\n```\nuvx cookiecutter -o </path/to/dir> --checkout v0.9.0 gh:alexkey/cookiecutter-uv-core\n```\n\nCookiecutter prompts for the following values and shows the default of each. Press Enter to accept a default:\n\n- `name` - the project's display name, for example`FooBar-baz` . The values`service_name` ,`repo_name` , and`env_prefix` derive from it.\n- `version` - the initial project version.\n- `brief` - a one-line package summary.\n- `description` - a longer description for the generated README.\n- `author_name` and`author_email` - the author and maintainer details.\n- `url` and`repository` - the URLs of the project homepage and the source\nrepository.\n- `license` - the[SPDX license identifier](https://spdx.org/licenses/) .\n- `uv_version` and`python_version` - the pinned*uv* and CPython versions. The\ngenerated code uses explicit lazy imports and therefore requires a`python_version` of 3.15 or later.[Changing the Python and uv Versions](#changing-the-python-and-uv-versions) lists the files that pin\nthem.\n- `docker_build_platform` - the target platform of Docker image builds.\n- `redis_image_tag` and`postgres_image_tag` - the image tags of the Docker Compose\nservices.\n- `postgres_user` - the PostgreSQL user.\n\nCookiecutter derives the following values from the inputs above and prompts for them as well. Accept the derived defaults unless the project needs other values:\n\n- `service_name` - the lowercased project name.\n- `repo_name` - the importable Python package name:`service_name` with hyphens\nreplaced by underscores.\n- `env_prefix` - the prefix of the settings environment variables: the uppercased part\nof`name` before the first hyphen or underscore, followed by an underscore.\n- `python_majmin` - the major and minor Python version.\n- `docker_compose_name` - the Docker Compose project name.\n- `docker_prefix` - the base path inside Docker images.\n- `year` - the current year.\n\nTo generate a sample project with the defaults only, pass `--no-input`:\n\n```\nuvx cookiecutter -o </path/to/dir> --no-input .\n```\n\nThe command creates the sample project `foobar_baz`, which serves for inspection and\nexperiments. `uvx cookiecutter --help` lists every Cookiecutter option.\n\nChange into the directory of the generated project and continue with\n[A Typical Session](#a-typical-session). [Features](#features) lists the targets of the Makefile.\n\nThe following steps take the sample project `foobar_baz` from environment setup to a\nrunning service.\n\nInitialize a Git work tree, lock the dependencies, create the virtual environment, and install the project:\n\n```\ncd foobar_baz\ngit init\nmake requirements\nmake venv\nmake install\n```\n\nThe `make` targets need no activated environment. Run any other command in the project\nenvironment with the prefix `uv run`, as in `uv run foobar-baz --help`.\nAlternatively, the project's `venv` helper activates the environment in the current\nshell:\n\n```\n. ./venv\n```\n\nCheck the formatting, run the analysis tools, and run the unit tests:\n\n```\nmake check-format\nmake lint\nmake test\n```\n\nBuild the image and start the service stack with Compose:\n\n```\nmake docker-build\nmake docker-compose\n```\n\n`make docker-compose` runs in the foreground and removes the stack, volumes included,\non exit. Run the remaining commands from a second shell while the stack runs.\n\nPoint the database URL at the PostgreSQL port that Compose publishes on `localhost`.\nExport it for the current shell:\n\n```\nexport FOOBAR_DATABASE_URL=\"postgresql+asyncpg://database:database@localhost:5432/database\"\n```\n\nAlternatively, set the same value in the project's `.env.local` file, which the\nsettings loader reads by default.\n\nRun the system tests against the running database:\n\n```\nmake autotest\n```\n\nStart the service, which logs its resolved configuration on startup:\n\n```\nuv run foobar-baz run\n2026-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\n2026-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\n...\n```\n\nReview the current state first:\n\n```\nmake requirements-check\nmake requirements-try\n```\n\n`make requirements-check` lists the installed packages and marks the outdated ones,\ntransitive dependencies included. `make requirements-try` lists the outdated direct\ndependencies and previews the upgrade that the constraints allow, without writing the\nlockfile.\n\nRaise the constraints of the outdated direct dependencies, then lock and install the upgrade:\n\n```\nmake requirements-bump\nmake requirements-up\n```\n\n`make requirements-bump` rewrites only `pyproject.toml`. It raises the `~=` and\n`>=` clauses to the latest releases and preserves the rest of each requirement as\nwritten. It reports a requirement whose other clauses would exclude the latest release\nand leaves that requirement unchanged. Lock any pending `pyproject.toml` change first,\nbecause the outdated versions come from the lockfile.\n\n`make requirements-up` re-resolves every package, transitive dependencies included, to\nthe newest versions that the constraints allow, then installs them. Run\n`make requirements` and `make install` instead to upgrade only the bumped\ndependencies and keep the other locked versions.\n\nConfirm the result, then run the checks and tests against the upgraded packages:\n\n```\nmake requirements-check\nmake lint\nmake test\n```\n\nThe `python_version` and `uv_version` prompts set the CPython and *uv* releases of\na new project, and `cookiecutter.json` holds their defaults. A generated project pins\neach release in several files, and no pin follows another. Change every pin of a\nrelease in one change. The following sections list the pins of each release.\n\nBoth releases meet in the base image tag of the Dockerfiles:\n\n```\nghcr.io/astral-sh/uv:<uv_version>-python<major.minor>-trixie-slim\n```\n\nAn image with this tag must exist for the new combination of releases. The uv\n[Docker guide](https://docs.astral.sh/uv/guides/integration/docker/) lists the published tags. A generated project holds three identical\nDockerfiles: `docker/Dockerfile.x86_64`, `docker/Dockerfile.arm64`, and\n`docker/Dockerfile.aarch64`. The Makefile selects one by the output of `uname -m`.\nEdit the tag in all three files.\n\nThe generated code uses explicit lazy imports and therefore requires 3.15 or later.\nReplace the lazy imports with regular imports and adapt the CLI startup tests in\n`tests/main/app/cli/test_cli.py` before switching to an earlier release. Releases\nbefore 3.14 also reject `except A, B:` without parentheses. Releases before 3.12 also\nreject type parameter lists and `type` aliases.\n\nA generated project pins the Python release in two forms.\n\nThe full version, such as `3.15.2`:\n\n- `.python-version` , which holds only the version;\n- `requires-python = \"~=3.15.2\"` in`pyproject.toml` ;\n- the `requires-python` line of the inline script metadata in`docker/scripts/wait_for_pg.py` and`etc/scripts/bump_requirements.py` .\n\nThe major and minor version, such as `3.15`:\n\n- the `Programming Language :: Python :: 3.15` classifier in`pyproject.toml` ;\n- the `-python3.15-` part of the base image tag in the three Dockerfiles;\n- `py-version` in`pylintrc` .\n\nTo 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:\n\n```\nmake requirements\nmake install\n```\n\n`make requirements` re-resolves `uv.lock` for the new `requires-python`.\n`make install` replaces a virtual environment whose interpreter differs from the new\nrelease and installs the locked packages into the new environment. Rebuild the image\nwith `make docker-build` before the next container target. Finish with the checks and\ntests:\n\n```\nmake lint\nmake test\n```\n\nA generated project pins the *uv* release in its full version, such as `0.13.7`:\n\n- `UV_VERSION` in the`Makefile` ;\n- the lower bound of the `uv_build>=0.13.7,<0.14` requirement in the`[build-system]` table of`pyproject.toml` ;\n- the `0.13.7-` prefix of the base image tag in the three Dockerfiles.\n\nThe upper bound of the `uv_build` requirement is the next minor release, such as\n`0.14` for `0.13.7`. The template derives it from `uv_version`. A patch release\nleaves the upper bound unchanged. A minor release raises it as well, such as to\n`<0.15` for `0.14.0`.\n\n`UV_VERSION` names the release that the host is expected to run.\n`make env-check-python` prints a warning when the installed *uv* differs from it.\nEvery target that locks the dependencies, installs them, builds a distribution, or\nruns the quality assurance tools runs this check first. A different release produces a\nwarning, not an error.\n\nThe `uv_build` requirement selects the build backend. The upper bound excludes the\nnext minor release, which can contain breaking changes. Without it, the source\ndistribution can fail to build once such a release is published, and *uv* warns about\nthe missing bound. *uv* builds the project with its bundled backend when its own\nrelease satisfies the requirement. Otherwise, it downloads a `uv_build` package that\nsatisfies the requirement.\n\nThe image runs the *uv* release of its base image tag. That release must read the\n`uv.lock` that the host writes. *uv* rejects a lockfile whose schema version is\nnewer than its own, and the schema version changes only in minor releases. Keep the\nhost and the image at the same release for that reason.\n\nTo change the *uv* release, edit every place in the list. Then install the same\nrelease on the host. A *uv* from the standalone installer updates itself to a given\nrelease:\n\n```\nuv self update 0.13.8\n```\n\nA *uv* from another installation method changes its release only through that method,\nsuch as its package manager. Confirm that the check no longer warns, then lock the\ndependencies and reinstall the project with the new release:\n\n```\nmake env-check-python\nmake requirements\nmake install\n```\n\nRebuild the image with `make docker-build` before the next container target. Finish\nwith the checks and tests:\n\n```\nmake lint\nmake test\n```\n\nThe generated project includes a Makefile whose targets are grouped by concern.\n\nThe following targets manage the virtual environment, the dependencies, and the package distributions:\n\n- Create a virtual environment: `make venv` .\n- Manage the dependencies and the lockfile: \n  - Update the lockfile: `make requirements` . Set`UV_LOCK_EXTRA_OPTS` to`--upgrade-package=<name>` to upgrade one package.\n  - Refresh all cached package data and update the lockfile:\n`make requirements-refresh` .\n  - List the outdated direct dependencies, then preview the upgrade without writing the\nlockfile: `make requirements-try` .\n  - Raise the `~=` and`>=` constraints of the outdated direct dependencies in`pyproject.toml` to their latest versions:`make requirements-bump` . Then update\nthe lockfile as[Updating the Dependencies](#updating-the-dependencies) describes.\n  - Re-resolve every package to the newest versions that the constraints allow, and\ninstall them: `make requirements-up` .\n  - List and validate the installed packages: `make requirements-check` .\n  - Display the dependency tree: `make requirements-tree` .\n- Update the lockfile: \n- Synchronize the virtual environment with the lockfile: `make install` . The target\nremoves packages that the lockfile does not list. Set`UV_SYNC_EXTRA_OPTS` to:\n  - `--all-extras` to include all optional dependencies;\n  - `--inexact` to keep packages that the lockfile does not list.\n Set `INSTALL_EXTRAS` to a space-separated list of names to include selected optional\ndependencies.\n- Reinstall all dependencies: `make force-install` .\n- Build the source and wheel distributions: `make dist` .\n\nThe following targets build images, run containers, and manage Docker resources:\n\n- Show all images, containers, and volumes: `make docker-info` .\n- Build an image from the Dockerfile: `make docker-build` . Set`DOCKER_EXTRA_OPTS` to`--progress=plain` to show the full build output.\n- Create and run a container from the image, removed on exit: `make docker-run` . Set`DOCKER_EXTRA_OPTS` to`--publish 127.0.0.1:8000:8000` to publish the container's\nport on the host.\n- Manage the service stack with Compose: \n  - Start the containers in the foreground, and remove them with their volumes on exit:\n`make docker-compose` ;\n  - Follow the logs from the running containers: `make docker-logs` ;\n  - Open a shell in the running service container: `make docker-shell` .\n Build the image with `make docker-build` before the first`make docker-compose` ,\nbecause the Compose file does not build it. To surface errors, warnings, and other\nproblems in the log stream, filter it with ripgrep:\n\n```\nmake docker-logs | rg -i \"(err|crit|kill|garbage|warn)\"\n```\n\n- Start the containers in the foreground, and remove them with their volumes on exit:\n- 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\nresources on the host, not only those of the project.\n\nThe following targets list source notes, analyze dependencies, and lint, format, and test the code:\n\n- List the source notes with `NOTES_CONTEXT` lines of surrounding context. Both\ntargets require a Git work tree.\n  - List all notes, sorted by tag: `make show-notes` .\n  - List the notes in the files of the last `GIT_DEPTH` commits and in modified files:`make show-notes-recent` .\n- List all notes, sorted by tag: \n- Find unused, missing, and transitive dependencies: `make check-deps` . Configure*Deptry* in the`[tool.deptry]` section of`pyproject.toml` . The target fails on a\nfreshly generated project, because`pyproject.toml` declares libraries that the\nshipped code does not import, such as*FastAPI* and*Celery* .*Deptry* reports each of\nthem as`DEP002` .\n- Analyze the code: \n  - Lint with *Ruff* :`make check-ruff` ;\n  - Perform static type checking with *ty* :`make check-ty` ;\n  - Perform static type checking with *Mypy* :`make check-mypy` ;\n  - Perform code analysis with *Pylint* :`make check-pylint` ;\n  - Run all of the above analysis tools: `make lint` .\n The `MYPY_OPTS` and`PYLINT_OPTS` variables and the`ruff.toml` ,`ty.toml` ,`mypy.ini` ,`pytest.ini` , and`pylintrc` files configure the quality assurance\ntools. The analysis and formatting targets check`src` ,`tests` , and`etc/scripts` .The dependency, analysis, formatting, and test targets run their tools through `uv run --locked` , at the versions in`uv.lock` . They require the virtual\nenvironment, the lockfile, and the installed tools.\n- Lint with \n- Manage code formatting: \n  - Detect unformatted files: `make check-format` ;\n  - Sort imports and format all Python files: `make format` .\n- Detect unformatted files: \n- Run tests: \n  - Run the unit tests in the `PYTEST_UNIT_DIR` subdirectory of`tests` :`make test` ;\n  - Run the system tests in the `PYTEST_SYSTEM_DIR` subdirectory of`tests` :`make autotest` .\n `make autotest` needs a reachable database. It fails unless`{{ cookiecutter.env_prefix }}DATABASE_URL` is set and valid, or`PYTEST_EXTRA_OPTS` passes`--skip-db` .Both targets accept `PYTEST_EXTRA_OPTS` to forward extra*Pytest* arguments and`PYTEST_CUSTOM_PATH` to restrict the run to specific paths.[Testing](#testing) describes\nthese and further variables.\n- Run the unit tests in the \n\nThe following targets list the targets and remove generated files:\n\n- View all available targets: `make help` .\n- Remove the tool caches and bytecode: `make clean` .\n- Remove the build and distribution output: `make distclean` .\n- Run both cleanups, then delete the virtual environment and the entire *uv* cache,\nwhich other projects share:`make mostlyclean` .\n\nThe generated service rests on three runtime facilities: typed configuration, structured\nlogging, and asynchronous database access. An application runtime and a *Click*\ncommand-line interface combine them into a runnable service.\n\nThe typed *Pydantic* model `Settings` holds the runtime configuration. A cached\naccessor returns it:\n\n``` python\nfrom {{ cookiecutter.repo_name }} import get_settings\n\nsettings = get_settings()\n```\n\n- Each setting reads the environment variable that carries its name with the project's\nprefix, for example `{{ cookiecutter.env_prefix }}LOG_LEVEL` and`{{ cookiecutter.env_prefix }}DATABASE_URL` . Names are case-sensitive. Environment\nvariables that match no setting are ignored.\n- Values also come from an environment file, by default `.env.local` in the working\ndirectory. Set`{{ cookiecutter.env_prefix }}ENV_FILE` to load another file. Process\nenvironment variables take precedence over the file. An entry in the file that matches\nno setting is rejected. The generated`.env.local` sets every setting, and the\nfields of`Settings` are the authoritative list.\n- `get_settings()` returns a cached singleton. Pass`reload=True` to discard the\ncache and rebuild the settings from the current environment.\n- `DATABASE_URL` is required and validated. It must use the`postgresql+asyncpg` driver and include a database name and either a host or a`host` query parameter\nthat names a socket directory. The settings hold it as a`SecretStr` , which stays\nmasked when the settings are logged or printed.\n\nLogging builds on *structlog* and formats records from *structlog* and from the standard\nlibrary alike. Configure it once during startup from the settings above:\n\n``` python\nfrom {{ cookiecutter.repo_name }} import get_logger, get_settings, setup_logging\n\nsettings = get_settings()\n\nsetup_logging(\n    log_level=settings.LOG_LEVEL,\n    log_format=settings.LOG_FORMAT,\n    enable_colors=settings.LOG_COLORS,\n)\n\nlogger = get_logger(__name__)\nlogger.info(\"service started\")\n```\n\n- Call `setup_logging()` once before the first log record. A later call reconfigures\nlogging and replaces the handler that the previous call installed.\n- `log_format` selects the renderer:`console` for human-readable output and`json` for machine-readable records, one object per line. Use`console` interactively and`json` in deployed environments. The console renderer formats\ntracebacks with*Rich* , which can take seconds for a long traceback and blocks the\nthread that logs.\n- `log_level` sets the threshold below which records are dropped. Level names are\ncase-insensitive.\n- Colors apply to `console` output on a TTY only and are suppressed when the`NO_COLOR` environment variable is set.\n- Create module-level loggers with `get_logger(__name__)` , and pass context as keyword\narguments. Guard expensive log preparation with`is_level_enabled(logger)` , which\nchecks the debug level by default.\n\nDatabase access uses asynchronous *SQLAlchemy* over the `postgresql+asyncpg` driver.\nHelper functions cover the full lifecycle: creating and disposing the engine, building a\nsession factory, and opening sessions that commit or roll back automatically:\n\n``` python\nfrom {{ cookiecutter.repo_name }} import get_settings\nfrom {{ cookiecutter.repo_name }}.app.db.database import (\n    create_engine,\n    create_session,\n    create_sessionmaker,\n    dispose_engine,\n)\n\nsettings = get_settings()\n\n# Create the engine and session factory once during startup.\nengine = create_engine(settings.DATABASE_URL, raise_on_exc=True)\nsessionmaker = create_sessionmaker(engine)\n\n# Open one session per unit of work; the block is a single transaction.\nasync with create_session(sessionmaker) as session:\n    await session.execute(...)\n\n# Dispose the engine once during shutdown.\nawait dispose_engine(engine)\n```\n\n- Create the engine once with `create_engine()` , and reuse it for the lifetime of the\nprocess, because it owns the connection pool. By default,`create_engine()` returns`None` when creation fails. Pass`raise_on_exc=True` to fail fast at startup\ninstead. Dispose the engine once during shutdown with`await dispose_engine(engine)` to close the pooled connections.\n- Build a single session factory per engine with `create_sessionmaker()` , and share it\nas the source of every session. Do not create an engine or a factory per request or\nper task.\n- `create_session()` is an async context manager that opens one session and wraps the\nenclosed block in a single transaction. The transaction commits when the block exits\ncleanly and rolls back on any exception. The session is always closed. Use one block\nper unit of work, and let the block own the transaction boundary. Do not call`session.begin()` or`session.commit()` inside it.\n  - With the default `raise_on_exc=True` , database errors and unexpected errors are\nre-raised after the rollback.`asyncio.CancelledError` always rolls back and\npropagates. Pass`context=...` to label a session in log records, and`verbose=True` to log each lifecycle step.\n- With the default \n- **The defaults** for the engine and the sessions live in`DEFAULT_ASYNC_ENGINE_PARAMS` and`DEFAULT_ASYNC_SESSION_PARAMS` . Read the active\nvalues there, and override any of them through keyword arguments to`create_engine()` and`create_sessionmaker()` .\n  - Sessions set `expire_on_commit=False` . With the*SQLAlchemy* default of`True` ,`commit()` expires the attributes, and the first later access to each attribute\ntriggers an implicit refresh SELECT. Under asyncio, that implicit I/O can run\noutside*SQLAlchemy* 's async bridge and raise`MissingGreenlet` . The tradeoff is\nthat objects are not re-fetched after a commit.A server-generated value from `server_default` ,`server_onupdate` , or`Computed` is available only when*SQLAlchemy* populated it during the flush,\ntypically through`RETURNING` . A value that was not populated stays expired, and\naccessing it triggers the same implicit I/O. A value that*SQLAlchemy* does not know\nto be computed on the server can stay stale in memory. Fetch such values explicitly\nwith`await session.refresh(obj, [...])` , and load relationships eagerly with`selectinload()` instead of relying on attribute access.\n  - 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\nwas dropped while idle.`pool_use_lifo` keeps traffic on a small set of\nconnections, which lets the surplus connections idle out on the server during quiet\nperiods.`pool_recycle` limits the connection age to 1800 seconds. Keep it below the\nshortest idle timeout of any component in the network path, such as a load balancer,\nNAT, or a connection pooler. An AWS Network Load Balancer closes idle TCP\nconnections after 350 seconds by default, which calls for a value such as 300\nseconds. PgBouncer closes idle client connections only when`client_idle_timeout` is set, and that timeout is disabled by default.`pool_pre_ping` detects stale\nconnections when they leave the pool, and`pool_recycle` keeps connections from\nreaching that state.\n\nThe service is a *Click* command-line program. An application lifespan provides the\nshared resources that each command needs while it runs.\n\nTwo entry points launch the service: the console script\n`{{ cookiecutter.service_name }}` and `python -m {{ cookiecutter.repo_name }}`. The\n`[project.scripts]` table of `pyproject.toml` declares the console script. Both call\n`main()`, which hands control to the *Click* group `cli`. The group parses the\narguments and dispatches to a subcommand.\n\nThe application lifespan owns the shared resources, not the individual commands.\n`app_lifespan()` is an async context manager that wraps a command body and holds the\nresources for its duration:\n\n- On entry, it creates the database engine and the session factory, and yields a shared\n`AppState` .\n- On exit, it disposes the engine whether the body returned or raised. The pooled connections are therefore released on every path.\n- `AppState` is a typed mapping of the resources that the lifespan provides to the\ncommand body. It carries the session factory. Further resources owned by the lifespan\nextend it.\n- When the engine cannot be created, the lifespan fails fast and exits with\n`EXIT_GENERAL_ERROR` instead of yielding a partially initialized state.\n\nThe 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.\n\nThe template ships one subcommand, `run`, whose body is a stub. It enters the lifespan\nand leaves a placeholder for the service's own logic. Further behavior goes into more\nsubcommands. Two mechanisms keep startup cheap:\n\n- `LazyGroup` imports a subcommand's module only when that command is resolved.\nInvoking one command never imports another.\n- Explicit lazy imports defer each module's dependencies until their first use. PEP 810\nadded them in Python 3.15. The group's `--help` imports every command module to show\nits short help, but those modules load none of their dependencies until a command body\nruns. As a result,`--help` and`--version` load nothing beyond the standard\nlibrary and*Click* .\n\nCreating a command therefore takes two steps. First, place a module that exposes a\n`click.Command` under `app/cli/commands/`, and import with `lazy` everything that\nonly the command body uses. For example, `app/cli/commands/healthcheck.py` reuses the\nlifespan and the decorators below:\n\n``` python\nimport click\n\nfrom {{ cookiecutter.repo_name }}.app.cli._decorators import (\n    announce,\n    configure,\n    run_async,\n)\nlazy from {{ cookiecutter.repo_name }}.app.runtime import app_lifespan\n\n@click.command(\"healthcheck\", help=\"Verify the database connection.\")\n@configure\n@announce\n@run_async\nasync def healthcheck_cmd() -> None:\n    async with app_lifespan() as app_state:\n        session_maker = app_state[\"session_maker\"]\n\n        # Open sessions from session_maker and run the check here.\n        ...\n```\n\nSecond, register the command object with one entry in the `_SUBCOMMANDS` mapping in\n`app/cli/__init__.py`. The key is the command name, and the value is the dotted path\nof the object:\n\n```\n_SUBCOMMANDS = MappingProxyType(\n    {\n        \"run\": \"{{ cookiecutter.repo_name }}.app.cli.commands.run.run_cmd\",\n        \"healthcheck\": \"{{ cookiecutter.repo_name }}.app.cli.commands.healthcheck.healthcheck_cmd\",\n    }\n)\n```\n\nThe group verifies that the entry names a `click.Command` when it loads the entry. The\nmodule is imported when the group's help is shown or when\n`{{ cookiecutter.service_name }} healthcheck` runs. Its dependencies are imported only\nwhen the command runs. A unit test fails when the group's `--help` or `--version`\nloads a third-party package other than *Click*. The test thereby detects an import on\nthe startup path that lacks the `lazy` keyword.\n\nThree decorators factor out the setup that every command shares. They stack beneath\n`@click.command` in a fixed order, as the example above shows:\n\n- `configure` resolves the settings and configures logging before the body runs.\nLogging therefore uses the effective configuration from the first record.\n- `announce` logs the resolved settings at debug level and then a version banner at\ninfo level. The debug record sits behind the level guard that[Logging (logging.py)](#logging-logging-py) recommends.\n- `run_async` adapts an`async def` body to the synchronous callback that*Click* expects, and drives the body to completion with`asyncio.run()` .\n\nDecorators wrap from the bottom up but execute from the top down. Logging is therefore\nconfigured first, the startup announcement follows, and the asynchronous body runs last.\nThe body enters `app_lifespan()` to acquire the shared resources for the lifetime of\nthe command.\n\nTests run under *Pytest*. `make test` runs the unit tests, and `make autotest` runs\nthe system tests:\n\n```\nmake test\nmake autotest\n```\n\n`make autotest` reserves `PYTEST_DEPLOYMENT` for the URL of a deployed service that\nsystem tests target. The default is `http://localhost:8000`. The target prints the\nvalue, and the shipped system tests do not read it.\n\nThe shared `tests/conftest.py` registers two markers, `slow` and `requires_db`.\nTest code applies them as `@pytest.mark.slow` and `@pytest.mark.requires_db`. Each\nmarker has an option that skips the tests that carry it:\n\n- `slow` marks tests that are expensive to run. Pass`--skip-slow` to skip them. The\noption has no effect until a test carries this marker.\n- `requires_db` marks tests that need a live database. Pass`--skip-db` to skip\nthem. Only the tests in`tests/system` carry this marker. As a result,`--skip-db` affects only`make autotest` .\n\nThe two options are independent and can be combined, for example\n`PYTEST_EXTRA_OPTS=\"--skip-slow --skip-db\"`.\n\nThe following Makefile variables customize a test run:\n\n- `PYTEST_EXTRA_OPTS` forwards extra arguments to*Pytest* , such as the skip options\nabove or any other*Pytest* flag.\n- `PYTEST_CUSTOM_PATH` selects a path under the target's test directory, down to an\nindividual module, class, or test. The test directory is`tests/main` for`make test` and`tests/system` for`make autotest` .\n- `PYTEST_DURATIONS` sets how many of the slowest tests the run reports, through the*Pytest* option`--durations` . The default is`10` .\n- `PYTEST_LOG_CLI` enables*Pytest* 's live logging, which streams each log record to\nthe console as the run proceeds. The default is`false` .`PYTEST_LOG_CLI_LEVEL` sets the threshold of live logging, by default`INFO` . Live records render through*Pytest* 's own formatter as a raw dict, not in the application's JSON or console\nformat. A traceback appears only for`log.exception()` records.\n- `PYTEST_CAPTURE` selects*Pytest* 's output capture mode, through the option`--capture` . The default is`fd` , or`no` when`PYTEST_LOG_CLI=true` .\n\nFor example:\n\n```\n# Run only the tests under tests/main/<subdir>.\nmake test PYTEST_CUSTOM_PATH=<subdir>\n\n# Run a single test by path.\nmake test PYTEST_CUSTOM_PATH=<path/to/module.py>::<TestClass>::<test_method>\n\n# Skip slow tests.\nmake test PYTEST_EXTRA_OPTS=--skip-slow\n\n# Skip tests that need a live database.\nmake autotest PYTEST_EXTRA_OPTS=--skip-db\n\n# Repeat a single test 10 times to surface flakiness, through the --count\n# option of the pytest-repeat plugin. Pair it with PYTEST_CUSTOM_PATH, and\n# pick a test that exercises cached or global state, such as the settings\n# singleton here.\nmake test \\\n  PYTEST_CUSTOM_PATH=app/core/test_config.py::TestGetSettings::test_reload_picks_up_changed_environment \\\n  PYTEST_EXTRA_OPTS=--count=10\n```\n\nThe suite shares the following helpers, importable as\n`from tests.utils import <func>`:\n\n- `fail_without_traceback(reason)` fails the current test and reports only`reason` ,\nwith no traceback. Use it for unmet external prerequisites, where a traceback adds no\ninformation.\n- `parse_json_lines(stream)` parses a captured JSON-log`StringIO` into a list of\nrecords, one`dict` per line, and skips blank lines.\n- `assert_log_event(stream, match, *, count=1, **fields)` asserts that exactly`count` captured records contain`match` as a substring of their`event` . Every\nmatch must also contain each`**fields` pair, for example`level=\"error\"` . The\nhelper returns the matches for further inspection.\n- `assert_log_exception(stream, match, exc_type, *, exc_value=None, level=\"error\")` asserts that a single matching record logged an exception of`exc_type` . It searches\nthe whole structured`exception` chain and optionally checks`exc_value` . Prefer\nit to indexing`record[\"exception\"]` by hand, because it does not depend on the\nposition of the exception in the chain.\n- `_database_url(...)` builds a database URL from individual components. Each\ncomponent defaults to a module-level constant:`_DRIVER` ,`_USER` ,`_PASSWORD` ,`_HOST` ,`_PORT` , or`_DATABASE` .`VALID_DATABASE_URL` is the URL with all\ndefaults. These values back the`database_*` fixtures below.\n\nFixtures are defined in `conftest.py` files and apply to every test at or below their\ndirectory. `pytest.ini` runs *pytest-asyncio* in auto mode. As a result, async tests\nneed no `@pytest.mark.asyncio` marker, and async fixtures use the plain\n`@pytest.fixture` decorator.\n\n`tests/conftest.py` serves the whole suite:\n\n- `rng` - a session-scoped, seeded`random.Random` . The test header shows the seed,\nand`{{ cookiecutter.env_prefix }}TEST_SEED` pins it. This file also registers the`slow` and`requires_db` markers above.\n\n`tests/main/conftest.py` serves the unit tests that `make test` runs:\n\n- `reset_logging_state` - automatic. It snapshots and restores the process-wide\nlogging state around every test, which keeps one test's logging configuration from\nleaking into the next.\n- `_isolate_settings` - automatic. Around every test, it removes the environment\nvariable of each`Settings` field and`{{ cookiecutter.env_prefix }}ENV_FILE` , and\nit clears the cached settings. It derives the variable names from the fields of`Settings` , which lets a new setting work without a fixture change.`.env.local` stays readable.\n- `valid_environment` - supplies a valid database URL and replaces`.env.local` with\nan empty environment file. Request it in a test that needs valid settings independent\nof the developer's`.env.local` .\n- `cap_json_logs` - configures JSON logging to a`StringIO` and yields it. Read it\nwith the helpers of`tests/utils.py` above.\n- `make_fake_stream` - a factory for a fake stream with a configurable`isatty()` ,\nwhich exercises the color and TTY decisions.\n- `database_driver` ,`database_user` ,`database_password` ,`database_host` ,`database_port` , and`database_name` - the individual URL components.`make_database_url` is the URL factory, and`valid_database_url` is the URL with\nall defaults. Assert against these fixtures instead of hard-coded URL strings.\n\n`tests/main/app/db/conftest.py` serves the database unit tests:\n\n- `make_fake_sessionmaker` - returns the`FakeSessionMaker` class. Pass an instance\nto`create_session()` in place of a real session factory. Its`session` attribute\nholds a`FakeSession` whose`transaction` is a`FakeTransaction` . Inspect them\nto assert commit or rollback without a live database.\n\n`tests/system/conftest.py` serves the system tests that `make autotest` runs:\n\n- `app_logging` - session-scoped and automatic. It configures logging as the\napplication does, which keeps local variables out of logged tracebacks.\n- `database_url` - session-scoped. It resolves the real database URL from`{{ cookiecutter.env_prefix }}DATABASE_URL` and fails the suite when the URL is\nunset or invalid, or the database is unreachable. Pass`--skip-db` to skip the suite\ninstead. The URL is a`SecretStr` , which keeps the password masked in the function\narguments that*Pytest* prints in tracebacks. Call`get_secret_value()` only where a\nplain string is required. The masking does not extend to the frames of*SQLAlchemy* and the database driver. Do not pass`--tb=long` ,`--full-trace` , or`--showlocals` where logs are shared.\n- `database_schema` - session-scoped. It creates a dedicated`itest_<random>` schema\nfor the run and drops it with`CASCADE` afterward.\n- `database_engine` and`database_sessionmaker` - a real engine bound to the\nconfigured database, disposed after each test, and a session factory bound to that\nengine.\n- `items_table` - creates an isolated table in the run schema and drops it after the\ntest.\n\nThe generated project is prepared for the coding agents *Claude Code* and *OpenAI\nCodex*. Both agents load its project instructions at the start of every session. They\nload one of its agent skills when a task calls for it or when the user invokes the skill\nby name.\n\nEach asset has one canonical copy, stored where *Codex* reads it. A post-generation hook\nsymlinks it into the location that *Claude Code* reads. Edit only the canonical copy:\n\n| Asset | Canonical copy ( *Codex* ) | Symlink ( *Claude Code* ) | \n|---|---|---|\n| Project instructions | `AGENTS.md` | `CLAUDE.md` | \n| General instructions | `AGENTS.override.md` | `CLAUDE.local.md` | \n| Reference files | `.agents/docs/<topic>.md` | none; read on demand | \n| Agent skills | `.agents/skills/<name>/` | `.claude/skills/<name>` | \n\nThe symlinks are relative and belong under version control with the rest of the project.\n\n`AGENTS.md` in the project root gives an agent the knowledge that it cannot infer from\nthe code: the mandatory rules, the commands of the development workflow, the project\nlayout, and an index of reference files. *Codex* reads `AGENTS.md` natively, as\n[Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) describes. *Claude Code* reads the symlink\n`CLAUDE.md`, as [How Claude remembers your project](https://code.claude.com/docs/en/memory) describes. From v2.1.277, *Claude\nCode* also reads `AGENTS.md` directly, but by default only when no `CLAUDE.md` or\n`CLAUDE.local.md` exists in the working directory or above it. The generated project\ncontains `CLAUDE.local.md`, and *Claude Code* therefore depends on the symlink.\n\n`AGENTS.override.md` in the project root holds general instructions that do not depend\non the project: output formatting, technical writing, documentation lookups for external\nlibraries, the use of *uv*, and code comments. *Claude Code* reads it through the\nsymlink `CLAUDE.local.md` and places it after `CLAUDE.md`. *Codex* reads at most one\ninstruction file per directory and prefers `AGENTS.override.md` to `AGENTS.md`. The\nfirst instruction in `AGENTS.override.md` therefore directs *Codex* to read\n`AGENTS.md`. *Codex* receives the project instructions through that file read, not\nthrough automatic loading.\n\nCookiecutter renders the instruction files. They therefore name the package, the console script, and the environment prefix of the generated project.\n\n**Organization**\n\nThe instructions keep the context that every session pays for small:\n\n- `AGENTS.md` is loaded into every session and holds only what applies to most tasks.\n- `AGENTS.override.md` is loaded into every session as well and holds only rules that\napply to any project.\n- The reference files under `.agents/docs` are not loaded automatically. The*Reference* table in`AGENTS.md` names the tasks that each file serves, and the\nagent reads a file when its task enters that area:\n  - `architecture.md` - components, startup flow, design decisions, configuration,\nlogging, and recipes for adding a command, a setting, or a shared resource;\n  - `database.md` - session and engine lifecycle, and the rationale behind the\ndefaults;\n  - `conventions.md` - code conventions that the analysis tools do not enforce on\ntheir own;\n  - `testing.md` - test layout, running tests, fixtures, and helpers;\n  - `workflows.md` - environment setup, quality checks, dependency management, builds,\nand execution plans;\n  - `infrastructure.md` - the Docker image, the Compose stack, and their targets.\n- Sections titled *Rules* are mandatory for the agent. All other content is context that\ninforms its decisions. Where that context disagrees with the code, the code wins, and\nthe instructions are corrected.\n\n**Verification**\n\nStart the agent in the root of the generated project and confirm that it loaded the instructions:\n\n- In *Claude Code* , run`/context all` .`CLAUDE.md` and`CLAUDE.local.md` appear\nin the list under*Memory files* .`/memory` does not confirm loading, because it\nalso lists the locations of files that do not exist.\n- In *Codex* , run`codex \"Summarize the current instructions.\"` . The summary cites the\nrules from both`AGENTS.override.md` and`AGENTS.md` . A summary that cites only`AGENTS.override.md` means that*Codex* did not follow the instruction to read`AGENTS.md` .\n\n*Codex* loads instruction files from the project root down to the working directory, and\nit typically takes the Git root as the project root. Initialize the Git work tree first\nto make the generated project that root, as [A Typical Session](#a-typical-session) shows.\n\n**Maintenance**\n\n- Edit `AGENTS.md` and`AGENTS.override.md` , never`CLAUDE.md` or`CLAUDE.local.md` .*Claude Code* refuses to write through the symlinks.\n- Keep the instruction at the top of `AGENTS.override.md` that directs the agent to\nread`AGENTS.md` . Without it,*Codex* does not see the project instructions.\n- 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.\n- Keep `AGENTS.md` under 200 lines, because*Claude Code* recommends that size for\nreliable adherence. The limit also keeps the file well within the 32 KiB that*Codex* reads from project instruction files by default. Move detail that serves one area into\na reference file, and list that file in the*Reference* table.\n- The template occupies `CLAUDE.local.md` and`AGENTS.override.md` . The agents\notherwise leave these file names to the user for personal or temporary project\ninstructions. Keep such instructions in the user-level files instead:`~/.claude/CLAUDE.md` for*Claude Code* and`~/.codex/AGENTS.md` for*Codex* .\n- In the template, the instruction files are Jinja templates. Cookiecutter copies the\nskills without rendering them. Use the `cookiecutter.*` variables in the instruction\nfiles for project-specific names, and keep literal Jinja delimiters out of their text.\n\nThe bundled skills use the open [Agent Skills](https://agentskills.io/) format and run unchanged in\n[Claude Code](https://code.claude.com/docs/en/skills) and [OpenAI Codex](https://learn.chatgpt.com/docs/build-skills). *Codex* reads the canonical copy of each skill in\n`.agents/skills/<name>`. The post-generation hook symlinks it into `.claude/skills`,\nwhich *Claude Code* reads.\n\nBundled Skills\n\n**Overview**\n\nThe `update-tests` skill creates new tests and improves existing ones at any test\nlevel. It assumes no language, framework, or layout, and learns the tooling,\nconventions, and test infrastructure from the project. Do not use it to debug a\nproduction defect behind a single failing test.\n\n**Usage**\n\nStart the agent in the project root and invoke the skill with a mode, a path, and optional instructions:\n\n```\n<create|update> <path> [instructions]\n```\n\nIn *Claude Code*, type `/update-tests` followed by the arguments. In *Codex*, mention\n`$update-tests` in the message. Both agents also select the skill on their own when a\nrequest asks to write, review, refactor, or stabilize tests. The request then supplies\nthe arguments.\n\nFor example:\n\n```\n# Create unit tests in a new directory for code that has none.\n/update-tests create tests/main/app/cli cover lazy subcommand loading\n\n# Create a single new test module.\n/update-tests create tests/main/app/test_runtime.py cover app_lifespan\n\n# Audit and refactor every test under a directory.\n/update-tests update tests/main/app/core\n\n# In Codex, direct the update toward a specific problem in one file.\n$update-tests update tests/main/test_logging.py focus on order dependence\n```\n\nThe 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.\n\n**Arguments**\n\n- `mode` (required) -`create` or`update` :\n  - `create` writes new tests at`path` for the code or behavior that the\ninstructions name;\n  - `update` audits the tests at`path` and refactors them to close coverage gaps,\nremove redundancy, strengthen weak assertions, and eliminate flakiness.\n When the first word is not a mode, the skill infers the mode from the request. It asks when the request supports both readings.\n- `path` (required) - one directory or test file, relative to the working directory.\nIt is the only location where the skill creates or changes tests. Changes to anything\nelse, such as production code, shared fixtures, or dependencies, are proposed and\napplied only after approval. In`update` mode, the path must contain tests. In`create` mode, it may name a directory or file that does not exist yet, provided\nthat its parent directory exists. Without a path, the skill asks for one instead of\nsearching the project.\n- `instructions` (optional) - free text after the path. In`create` mode, it names\nthe code or behavior to test. Without instructions, the skill extends the existing\ntests at`path` , and it asks what to test when there are none. In`update` mode,\nthe instructions narrow or direct the work, for example toward a specific problem.\nThey can also extend the work to code that no test at`path` exercises. Without such\ninstructions, the skill lists that code as a follow-up, with the`create` invocation\nthat would cover it.\n\n**Overview**\n\nThe `develop` skill carries a substantial change from requirements to working,\ndocumented code in three stages: planning, implementation, and optional testing. Each\nstage starts only on the user's explicit approval. The skill suits new projects, new\nfeatures, ports from another codebase, language, or platform, imports of external\nfunctionality, reimplementations, and integrations between existing systems. Like\n`update-tests`, it assumes no language, framework, or layout and learns them from the\nproject. Do not use it to fix a single defect, make a small edit, refactor without\nchanging behavior, or work only on tests.\n\n**Usage**\n\nStart the agent in the project root and invoke the skill with an optional plan path and a task:\n\n```\n[plan-path] <task>\n```\n\nIn *Claude Code*, type `/develop` followed by the arguments. In *Codex*, mention\n`$develop` in the message. The skill runs only when invoked by name. The agents do not\nselect it on their own, and an ordinary request does not start the staged process.\n\nFor example:\n\n```\n# Plan a new feature; the plan goes to docs/exec-plans/active/.\n/develop add a migrate command that applies database schema migrations\n\n# Port behavior from another codebase.\n/develop port the retry policy of ../legacy-worker into the runtime\n\n# Keep the plan at a chosen path, then resume it in a later session.\n/develop docs/exec-plans/active/2026-11-12-health.md add a health command\n/develop docs/exec-plans/active/2026-11-12-health.md\n\n# In Codex, integrate an external system.\n$develop integrate the Redis cache from the Compose stack into the runtime\n```\n\nThe skill restates the task, the plan location, and the starting stage before doing any work, and ends each stage with a report.\n\n**Stages and approval**\n\n1. *Planning.* The skill studies the project, pins down the requirements, and designs\nthe change. It uses a planning skill and the agent's plan mode when they are\navailable. The default planning skill is[brainstorm](https://github.com/umputun/cc-thingz#brainstorm) . The stage ends with an\nexecution plan, and nothing in the project changes before the plan is approved.\n2. *Implementation.* After approval, the skill saves the plan, records a baseline of the\nchecks and tests, and implements the plan milestone by milestone, keeping the plan\ncurrent. A significant deviation, such as a changed requirement, interface, or\ndependency, waits for approval. Existing tests that an approved behavior change\ninvalidates are updated in this stage, without weakening the coverage of unchanged\nbehavior. New tests are not written. The stage ends with a report and the question\nwhether to proceed with testing.\n3. *Testing (optional).* The skill creates or updates the tests through`update-tests` only when the user agrees, with one full invocation per approved target. The user may\napprove all proposed targets or a subset. The targets declined or left out are\nrecorded as follow-ups in the plan and the tech-debt tracker.\n\nApproval 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.\n\n**Arguments**\n\n- `plan-path` (optional) - the execution plan, relative to the working directory. An\nexisting plan is resumed. A path that does not exist yet names the new plan file. The\nskill asks before using a path whose parent directory is missing, and it points out a\nlocation outside`docs/exec-plans/` before approval. Without a plan path, the plan\ngoes to`docs/exec-plans/active/` .\n- `task` - free text that states the goal or points to the requirements, such as a\nspecification, an issue, or the code to port. It may be omitted when the plan path\nresumes a plan.\n\n**Execution plans**\n\nPlans follow OpenAI's [ExecPlans](https://developers.openai.com/cookbook/articles/codex_exec_plans) methodology. Each plan is a living, self-contained\ndocument from which a later session can finish the work. It holds a progress log, a\nrecord of discoveries, a decision log, and a retrospective. The skill keeps the plans in\nthe layout that [Harness engineering](https://openai.com/index/harness-engineering/) describes:\n\n```\ndocs/exec-plans/\n    active/                 plans in progress\n    completed/              completed and cancelled plans\n    tech-debt-tracker.md    deferred work and known shortcuts\n```\n\nA plan's file name is its creation date in ISO 8601 form followed by a short kebab-case\ndescription, such as `2026-11-12-health-command.md`. Every date and time in the plans\nand the tracker is in UTC. A small change without design decisions gets a lightweight\nplan. That plan needs approval like any other, but the skill saves it only when a plan\npath is given. Project guidance in a file such as `AGENTS.md` may prescribe another\nlocation than `docs/exec-plans/`.\n\n**Development standards**\n\nThe skill holds the implementation to built-in standards for completeness, correctness\nand reliability, security, simplicity, maintainability, testability, and documentation.\nIt checks them itself before it reports the implementation as complete. The standards\nturn review criteria into development rules: requirements traced to code and wired end\nto end, errors and resources handled on every path, input validated and secrets kept out\nof code and logs, the direct solution preferred over speculative abstraction, and user\ndocumentation, agent instructions, and the plan updated in the same change. Test quality\nremains the responsibility of `update-tests`.", "url": "https://wpnews.pro/news/show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates", "canonical_source": "https://github.com/alexkey/cookiecutter-uv-core", "published_at": "2026-11-16 17:09:48+00:00", "updated_at": "2026-11-16 17:26:47.078771+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["cookiecutter-uv-core", "Cookiecutter", "uv", "Pydantic", "structlog", "SQLAlchemy", "PostgreSQL", "Claude Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates", "markdown": "https://wpnews.pro/news/show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates.md", "text": "https://wpnews.pro/news/show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates.txt", "jsonld": "https://wpnews.pro/news/show-hn-cookiecutter-uv-core-uv-template-with-an-agent-sdlc-and-quality-gates.jsonld"}}