diff options
Diffstat (limited to 'content/blog/2026-01-26-good-for-people-good-for-agents-documentation-and-uniform-tooling.md')
| -rw-r--r-- | content/blog/2026-01-26-good-for-people-good-for-agents-documentation-and-uniform-tooling.md | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/content/blog/2026-01-26-good-for-people-good-for-agents-documentation-and-uniform-tooling.md b/content/blog/2026-01-26-good-for-people-good-for-agents-documentation-and-uniform-tooling.md new file mode 100644 index 0000000..b863ed4 --- /dev/null +++ b/content/blog/2026-01-26-good-for-people-good-for-agents-documentation-and-uniform-tooling.md @@ -0,0 +1,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.", classes="shrink") %} +{{ 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. |