Three clean code rules for agents, enforced by tools

You used to write the code yourself and remember why each decision was made. An agent starts every session from zero and copies whatever pattern it finds. A messy repo costs you tokens on every session, and its output gets messier.

So I keep three hard rules, and a machine checks each one. A rule nobody enforces is only a wish.

Rule 1: each part does its own job

An agent making a small change should only read a few files. In my backend the direction of every import is fixed, and code goes through layers in one direction:

output

api > schemas > services > selectors > models

import-linter fails the build if a layer reaches the wrong way. This is the real contract from my pyproject.toml:

toml

[[tool.importlinter.contracts]]
name = "inside each app: api > schemas > services > selectors > models"
type = "layers"
containers = ["apps.accounts", "apps.content"]
layers = ["(api)", "(schemas)", "(services)", "(selectors)", "(models)"]

bash

PYTHONPATH=src uv run lint-imports

output

Contracts: 5 kept, 0 broken.

Rule 2: comments are correct, every function has a docstring

The agent trusts what it reads. A wrong comment sends it the wrong way, so comments explain why, and every public function gets a Google style docstring:

python

def minutes(self, body_en: str, body_fa: str) -> int:
    """Return the reading time of the longer body.

    Args:
        body_en: English Markdown source.
        body_fa: Persian Markdown source.

    Returns:
        Whole minutes, at least 1.
    """

Ruff enforces it, along with everything else it can check:

toml

[tool.ruff.lint]
select = ["ALL"]

Rule 3: no dead code

When the agent sees an old login beside the current one, it has to guess which is real, and sometimes it guesses wrong. Removed code gets deleted, not commented out and not flagged off. Git remembers it. Ruff's ERA rules catch commented out code, which select = ["ALL"] already turns on.

Pay once

Keeping a repo this clean used to be expensive, so most teams lived with the mess. Now an agent does the cleanup. You pay once, and every later session reads less and gets more right.

Copy this into your CLAUDE.md

markdown

## Code rules
- Each module does one job. Respect the import direction: api > services > selectors > models.
- Every public function, class and module has a Google style docstring.
- Comments explain why, never what. Fix or delete a comment that is wrong.
- No dead code. Delete what is unused, including old versions. Git keeps the history.
- Before you finish, run the linters and the tests, and report their real output.

Run the checks in CI too, so no session can skip them.

PreviousFrom a missing fcntl error to a real Linux setup on Windows NextCutting a reel frame by frame with FFmpeg

1	You used to write the code yourself and remember why each decision was made. An agent starts every session from zero and copies whatever pattern it finds. A messy repo costs you tokens on every session, and its output gets messier.
2
3	So I keep three hard rules, and a machine checks each one. A rule nobody enforces is only a wish.
4
5	## Rule 1: each part does its own job
6
7	An agent making a small change should only read a few files. In my backend the direction of every import is fixed, and code goes through layers in one direction:
8
9	```text
10	api > schemas > services > selectors > models
11	```
12
13	`import-linter` fails the build if a layer reaches the wrong way. This is the real contract from my `pyproject.toml`:
14
15	```toml
16	[[tool.importlinter.contracts]]
17	name = "inside each app: api > schemas > services > selectors > models"
18	type = "layers"
19	containers = ["apps.accounts", "apps.content"]
20	layers = ["(api)", "(schemas)", "(services)", "(selectors)", "(models)"]
21	```
22
23	```bash
24	PYTHONPATH=src uv run lint-imports
25	```
26
27	```text
28	Contracts: 5 kept, 0 broken.
29	```
30
31	## Rule 2: comments are correct, every function has a docstring
32
33	The agent trusts what it reads. A wrong comment sends it the wrong way, so comments explain why, and every public function gets a Google style docstring:
34
35	```python
36	def minutes(self, body_en: str, body_fa: str) -> int:
37	"""Return the reading time of the longer body.
38
39	Args:
40	body_en: English Markdown source.
41	body_fa: Persian Markdown source.
42
43	Returns:
44	Whole minutes, at least 1.
45	"""
46	```
47
48	Ruff enforces it, along with everything else it can check:
49
50	```toml
51	[tool.ruff.lint]
52	select = ["ALL"]
53	```
54
55	## Rule 3: no dead code
56
57	When the agent sees an old login beside the current one, it has to guess which is real, and sometimes it guesses wrong. Removed code gets deleted, not commented out and not flagged off. Git remembers it. Ruff's `ERA` rules catch commented out code, which `select = ["ALL"]` already turns on.
58
59	## Pay once
60
61	Keeping a repo this clean used to be expensive, so most teams lived with the mess. Now an agent does the cleanup. You pay once, and every later session reads less and gets more right.
62
63	## Copy this into your CLAUDE.md
64
65	```markdown
66	## Code rules
67	- Each module does one job. Respect the import direction: api > services > selectors > models.
68	- Every public function, class and module has a Google style docstring.
69	- Comments explain why, never what. Fix or delete a comment that is wrong.
70	- No dead code. Delete what is unused, including old versions. Git keeps the history.
71	- Before you finish, run the linters and the tests, and report their real output.
72	```
73
74	Run the checks in CI too, so no session can skip them.
75

en3 min read