1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
+++
title = "Good for People, Good for Agents. Uniform Tooling and Documentation Repositories."
description = "How a central documentation repository and uniform tooling can make work better for people and the agents they use."
[extra]
visual_aid_src = "/img/posts/robots.png"
visual_aid_alt = "Five rectangles with different patterns have rays pointing to a bigger rectangle that is being held by a robot on the left, and a happy person on the right"
[taxonomies]
tags = ["Best Practices", "Agents", "Documentation"]
categories = ["Software Engineering"]
+++
Many practices that are helpful for teams to collaborate, are also helpful to
improve how we work with agents. In this post I’d like to share how having
a centralized record for decisions and documentation, and a uniform tool to
build, run, and test projects can help people and the agents they build with.
<!-- more -->
{% window(title="Visual Aid.") %}
{{ hero() }}
{% end %}
## Practice I, a Shared Documentation and Decision Repository.
### What It Is.
A repository that stores a record of your decisions as a team, and the current text of your practices: naming conventions, tooling choices, code quality standards, etc.
### Why It’s Good For People.
Treating our practices and agreements like any other repository makes it come alive: Anyone can submit a merge request to change how we work, and the history and discussion around our decisions is easy to read back.
This repository becomes the record for both *how we do* and *why we do*. It’s helpful when onboarding new teammates, as long term memory for retrospectives, and as a reminder of the way we agreed we’d like to work (See: [Internal Processes](https://wiki.r.bdr.sh/view/welcome-visitors/view/engineering-management/view/internal-processes) in the wiki)
### How to Implement It.
1. Create a repository.
2. Open a Merge Request that creates a “README.md” with a description of how to use it: How to make a proposal, how consensus will be reached.
3. Discuss, modify and agree.
4. Merge, and you have your first decision logged!
## Practice II, Standardized Commands Across Projects.
### What It Is.
A `Makefile` you add to every repository, with a set of agreed on commands to do common tasks: build, run, test, benchmark, lint, etc.
### Why It’s Good For People.
At a certain level of complexity, it’s likely that your team will work with more than one project, sometimes with more than one technology.
If this is the case, it’s a lot easier to remember “`make dev` runs the server” instead of `pnpm run dev` (or are we using `yarn`?), `uv run flask run` (or was it `poetry`?), `cargo run`, `flutter run`.
### How to Implement It.
1. Create an empty Makefile with common commands. Here’s some ideas:
- `prepare` installs dependencies.
- `build` builds the bundle / binary.
- `dev` runs the application in development/watch mode.
- `lint` runs the formatter and linter in check mode.
- `format` runs the formatter and linter in fix mode.
- `test` runs tests.
- `coverage` prints out a code coverage report.
- `benchmark` runs the performance benchmarking suite.
- `audit` runs dependency / license auditing.
2. Add the empty Makefile to your shared documentation repository and explain what each command should do.
3. Add the Makefile to each of your repositories, it’s likely to be a simple mapping to the existing language’s tooling.
## Making them also good for Agents.
Now that you have these tools, it’s very easy to make your agent aware of them. My documentation repository is called `readme.doc` , and I use Claude Code, so in the CLAUDE.md` for each repository, I add the following line:
```
Follow practices as described in @../readme.doc/CLAUDE.md
```
This `CLAUDE.md` in the repository is a “machine entry point” for documentation, and looks like this:
```
Read @project-build-and-run-guidelines.md to understand how to build, lint, test, and run local tasks.
Before writing any code read @code-quality-guidelines.md
Before interacting with services, read @service-url-naming-guidelines.md
Before creating any new repo read @repository-naming-guidelines
```
This will give the agent a better starting point, and will output code that is more in line with my coding standards. For example, I don’t like that Claude often uses abbreviations for variable names, or that it tends to always add code, so my code quality guidelines will include entries like this:
```
- Don't use abbreviations for variables, eg. prefer coordinates to coords.
- Start by writing tests, and validate it worked when the tests pass.
- Use code that's idiomatic for the language you're writing for.
- Consider subtractive improvements. Consider how removing code can solve the problem before adding.
- Avoid very large functions, break into pieces with a single responsibility.
- Avoid generic module names like "utils", each module should have a specific concern.
- Prefer keeping generic functionality at the core, with specific logic at the leaves.
```
And that’s it. The code quality will be better, and by allowing calls to `make`,
easier to run without interruptions.
You can read more about these practices in the wiki pages for
[Central Documentation Repository](https://wiki.r.bdr.sh/view/central-documentation-repository),
and [Standardized Makefile](https://wiki.r.bdr.sh/view/standardized-makefile)
where I'll continue to build up the concept and connect it with the patterns it enables.
|
