Redactr: building an internal tool with AI agents, a brief post-mortem on process

Some time ago, in my spare hours, I built Redactr, a small internal CLI tool for my day-to-day work at Atlassian. I can’t publish the code itself: it lives inside a product ecosystem I can’t name, and the details of what it does are locked down. But I’ve set it up so my team can use it internally and even contribute if they feel like it. The process behind it is entirely mine to share, and honestly, that’s the part worth keeping.

Redactr is a command-line program for sanitizing files in a reversible way. Nothing grand, no platform, no multi-team rollout. Just a small, focused utility written almost entirely through an AI coding agent, in Go, using only the standard library, built to be lightweight and customizable. What surprised me wasn’t that the agent wrote decent code. It was how much of the quality came from decisions I made before the agent wrote a single line.

This post is a story about process, not a code walk-through. If you’re a developer, an architect, or just curious how AI is changing the craft, there might be something here for you.

Design first, agent second

The very first thing I did was write a design doc. Real requirements, not scribbles: lightweight, customizable, reversible, and whatever else the team’s day-to-day actually needed. Capturing those priorities up front kept the build honest.

Why start there? Because an AI agent is brilliant at executing a precise brief and unreliable at inventing one. The design doc pinned down the non-negotiables before any code existed, and turned the agent from a clever tool into a disciplined one. If you’ve never read a great design doc, DesignDocs.dev keeps a huge library of real examples from engineering orgs. It’s the best argument I know for write-before-you-build.

Why Go, and why agents love it

Language choice came early. I went with Go for the reasons any Go fan would recite: it compiles to a single lightweight binary, it’s fast, and its error handling is explicit. Hard to ignore, easy to trust. But there was a second, less obvious pull: Go is genuinely great with AI agents.

Agents work best with strong defaults and unambiguous conventions. Go’s opinionated tooling, gofmt, the module system, the standard library, hands an agent guardrails it can lean on. Fewer ways to do a thing means fewer ways to do it wrong. When the whole point is delegating work you can’t fully watch, that determinism is worth its weight in gold.

Clean meets hexagonal

For the skeleton I aimed at a blend of Clean Code and Hexagonal architecture. In plain words: separate responsibilities cleanly, and isolate the core of the app from the outside world, meaning storage, I/O, the things that change.

The payoff showed up exactly where I hoped: when the product grew, the seams held. New needs plugged into the edges without tearing out the middle. That’s the whole promise of hexagonal architecture, and it’s why a worker with clean seams lets you move faster over time without breaking things.

The AGENTS.md experiment

The most interesting part of the build. Instead of letting the agent improvise, I wrote an AGENTS.md file that told it exactly how to operate on this project: commands, conventions, workflow, the works. AGENTS.md is the fast-growing open format becoming a de facto standard, a README for agents, a predictable place to tell a coding assistant how to work on your repo. It works across Codex, Jules, Cursor, opencode and dozens of other agents. Documentation written for a machine instead of a human.

For language-level flair, I added agent skills for Go. Agent Skills package procedural knowledge, like style, error handling and testing patterns, that agents load on demand. I pulled in a curated Go skill set such as cc-skills-golang so the agent operated with real Go instincts instead of generic guesses. The model that clicked for me: AGENTS.md for project context, skills for language expertise.

Discipline: stdlib only, test-oriented, gitflow

Three decisions kept the project boring in the best way.

First, standard library only. No external dependencies. Fewer supply-chain risks, smaller binary, and a surface the agent could never mismatch versions on. It constrained the toolbox and simplified everything.

Second, test-oriented development. Tests became the contract with the agent. If it wrote code, I could verify it did what I asked. With something that writes faster than it reasons, tests are the only feedback loop you can trust.

Third, gitflow. A real branching discipline kept the collaboration sane. The agent worked on features, I reviewed the shape of the changes, and nothing chaotic leaked into main.

What actually worked, and what it means for you

Strip away the specifics and the transferable part is a five-step workflow for any AI-assisted build:

1. Write the design doc first. A precise brief turns an agent from a clever improviser into a disciplined engineer.
2. Pick a language with strong defaults. Opinionated tooling and explicit error handling make delegated code predictable.
3. Design seams before scale. Clean and hexagonal separation means growth doesn’t mean rewriting.
4. Document for the machine. An AGENTS.md plus language skills is the modern way to brief an agent properly.
5. Make tests the contract. With an agent, tests aren’t just good practice, they’re the only verification you’d trust.

The honest lesson, the one I keep coming back to: the agent wrote the code, but the architecture was mine. AI accelerates execution. The design, the decisions, the discipline, that’s still the engineer’s job, and it decides whether the speed builds something great or something brittle. That’s the part worth stealing.

Resources

A few things I leaned on while building Redactr, worth keeping in your own back pocket:

• AGENTS.md, the open format for giving coding agents reliable project instructions.
• Agent Skills, a standardized way to bundle procedural knowledge agents load on demand.
• cc-skills-golang, a solid set of Go skills to hand an agent before it starts writing.
• DesignDocs.dev, a curated library of real design doc examples and templates.