Simon, I really enjoy your live coding sessions. If you do another one, would you mind showing this part as well? It would be extremely educative.
I haven't been able to do without an `.MD` - no agent (CC, Codex, OpenHands) was smart enough to figure out my layout unguided. So much so, a few weeks ago, I had Claude write the guideline below to document the way I like to lay out my tests and modules. I make extensive use of uv workspaces and don't ship tests to production deployments:
```
- uv Workspace Architecture (`uv` v0.11.8+, `packages/` members):
**Build tool:** Exclusively `uv_build`. Never `hatchling` or any other build backend.
Pin as `uv_build>=0.6` in every `[build-system]` block.
**Naming convention — flat, distinct package names (NOT a shared namespace):**
Each workspace member uses a *flat* Python package name that is unique across the workspace.
The `uv_build` backend auto-discovers the module by converting the project name (hyphens → underscores):
`base-constants` → `src/base_constants/__init__.py`
`base-domain` → `src/base_domain/__init__.py`
`base-geometry` → `src/base_geometry/__init__.py`
etc.
No `[tool.uv.build-backend] module-name` override is needed because the project name already maps directly.
**Why NOT a `base.*` namespace package:**
`uv_build` cannot support PEP 420-style namespace packages across workspace members.
It maps each project name to exactly one module root; only one member can own `base/__init__.py`.
Attempting `module-name = "base.constants"` treats the dotted name as a nested directory,
not a namespace — it looks for `src/base/constants/__init__.py`. Confirmed by binary string
inspection of the `uv` binary. NEVER attempt namespace packages with this build backend.
**Import style (locked, never change):**
`from base_constants import CONSTANT_A`
`from base.constants import CONSTANT_A` (namespace layout — abandoned)
**Tests member:** `package = false` in `[tool.uv]`, no `[build-system]` block at all.
Tests are never shipped in production; the member exists solely to isolate test dependencies.
**Microservice split story:** When a member needs to become a standalone repository,
only the `[tool.uv.sources]` entry in the consuming `pyproject.toml` changes
(workspace source → PyPI or VCS source). The package code itself is unchanged.
- *Future-phase features: stub, NEVER implement.* When a feature is explicitly
scoped to a later phase (e.g., "Phase 4"), write a one-line stub that raises
`NotImplementedError` plus a docstring describing the Phase 4 contract. A full
implementation spends tokens on untested code that may never ship in its current
form. Exception: if the full implementation is ≤ 5 trivial lines and directly
validates the current phase's math, implement it outright.
```
Similarly, I find it annoying that every agent uses f-strings inside logging calls. Since I added this, that hasn't been a problem:
```
- NEVER use f-strings or .format() inside logging calls. This forces the string to be interpolated immediately, even if the log level (like DEBUG) is currently disabled. You should NEVER do this and if you notice this in existing code, FLAG IT immediately!
By passing the string and the variables separately, you allow the logging library to perform lazy interpolation only when the message is actually being written to the logs. It also increases the caridinality for Structured Logging rendering observability useless!
BAD:
```python
# The f-string is evaluated BEFORE the logging level is checked.
# This:
# - wastes CPU cycles if the log level is higher than INFO
# - increases the caridinality for Structured Logging rendering observability useless!
log.info(f"denominator {denominator} is negative!")
```
GOOD:
```python
# The ONLY right way - logging module only merges the variable into the string if
# the INFO level is actually enabled.
log.info("denominator %s is negative!", denominator)
```
Note: Using this "Good" pattern ALSO helps with Structured Logging. Tools like Sentry or ELK can group logs by the template string ("denominator %s is negative!") rather than seeing every unique f-string as a completely different error type.
```