Add a blog

2 files changed, 111 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.
diff --git a/content/blog/_index.md b/content/blog/_index.md
new file mode 100644
index 0000000..4082cb6
--- /dev/null
+++ b/content/blog/_index.md
@@ -0,0 +1,8 @@
++++
+title = "Blog"
+description = "Blog about Engineering and Leadership at Holistic Services, written by Rubén Beltrán del Río."
+template = "blog.html"
+sort_by = "date"
+page_template = "blog_post.html"
+paginate_by = 10
++++