Good for People, Good for Agents. Uniform Tooling and Documentation Repositories.

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.

Visual Aid.

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 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. It's a small change on your end, and you'll get higher quality code for every prompt, and easier hands-free development around patterns like red green refactors, or benchmark optimizations.

You can read more about these practices in the wiki pages for Central Documentation Repository, and Standardized Makefile where I'll continue to build up the concept and connect it with the patterns it enables.