Team-building with AI

I set Televism up from the very start to build it together with AI agents. Even so, a human and an agent don’t automatically become a working team just because both are working on the same project.

We first had to find our rhythm: figuring out how we develop ideas, who makes which decisions, and when an idea actually turns into code. So before we could work together productively, we needed shared rules of the game first.

Setting the rules first

A team that’s just coming together sorts out one thing before anything else: how it works together. Who does what? What gets agreed on, what runs on its own? For us, this working model lives in a single file: AGENTS.md. It’s our shared rulebook, not a technical document — it describes how work on Televism is done, not what gets built.

It states, for example, that we work new features out in the functional spec first. They’re then translated into a technical design. Only once I’ve approved that design does any code get generated.

The effort is meant to move deliberately to the front: into aligning on the approach and building a shared understanding. By the end, as much as possible should already be clear, so that no surprises come up when the code is generated. Our rules of the game also spell out the hard guardrails: what may the agent decide on its own, and what not? Commits and pushes, for instance, it only makes on explicit request — never on its own, not even to wrap up a task.

The functional spec and the technical concept aren’t throwaway planning documents for a single task, but the project’s living documentation. That helps with alignment — and has a second benefit we’ll come back to later.

For a concrete task, I come with an idea. We brainstorm it first, then the agent extends the concept with that idea. All I have to do afterwards is review the diff to see whether we share the same understanding. At the level of the technical concept — TK for short — this carries on, at least as far as I want to keep control.

The implementation is something the agent now handles on its own. That wasn’t a given at the start either, but that’s a topic for its own post. I only skim the finished code, mainly for whether it touched the packages, files, and tests I expected.

No dressed-up personas

We’re both wearing many hats: product owner, architect, tester, infrastructure engineer, and security engineer.

I’m happy to get help with all of it. But there’s one thing I deliberately don’t do, even though it’s recommended everywhere: I don’t give the agent personas.

I’ve played around with it and never noticed a difference whether I tell an agent or LLM: “You are a very experienced software developer, specialized in Spring applications, with a high awareness of quality and deep knowledge of blah blah blah. Review this code.” Or simply: “Review this.”

What it needs isn’t a costume, but the right document at the right moment. For the cross-cutting roles it takes on over the course of a task, there are dedicated guides, linked from AGENTS.md. Setting up a new feature, building a time-triggered job, writing an integration test, making visible text translatable: for each of these cross-cutting topics there’s a guide of its own.

Not “imagine you were a tester,” but “this is how we test here.” That’s the difference between role-play and craft.

A partner with amnesia

Now for the catch: my new partner suffers from amnesia.

It’s not as if I onboard him once and he then knows the ropes forever. He starts every task from scratch. No knowledge of the project, no memory of what we built together last week. All he has to go on is whatever is in his context right now. Nothing else.

This is where the documents from earlier come back into play. It’s not only easier for me to talk with the agent at the level of the functional spec and TK rather than at the code level. It’s also easier for him to load compressed knowledge about the project from the documentation instead of piecing it all together from the code.

There’s plenty to keep in mind here too: small, clearly delineated files, plus links from the code into the documentation and back. But more on that elsewhere.

A home for a forgetful partner

Shared rules build trust: not because they make the agent perfect, but because they make sure we’re talking about the same problem. Then I don’t have to follow every line of code; I can check whether the concept, the spots it touches, and the tests fit together.

For that, the agent needs a home suited to its nature: rules have to be findable, knowledge compact and linked, and getting into the project has to work even without any backstory.