alt Hacker NewsMost of my projects are without an AGENTS.md/CLAUDE.md at the moment. I've found that if the project itself is in good shape - clear docs, comprehensive tests - you don't need to tell the coding agent much in order for it to be productive.
I start a whole lot of my sessions with "Run tests with 'uv run pytest'" and once they've done that they get the idea that they should write tests in a style that fits the existing ones.
Replies
Wouldn't the AGENTS.md containing the line, "When you make changes, they should be tested. Run tests with `uv run pytest`" basically have the same effect and save you some typing? I've never used AGENTS.md myself but I'd like to look into it because I find my agent rediscovering using a bunch of file reads very frequently in my current project.
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.
```
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.
That's wild. I couldn't live without my AGENTS to make sure it keeps to the coding styles I prefer. Especially needed on greenfield projects.
A lot of my projects are built with platform versions from the last 12 months which had zero or very small amounts in the core training for the LLM, so they'll tend to avoid using the latest language options unless you prescribe them in AGENTS.