A Disciplined Agent Workflow: Lessons From Acceldata's Engineering Team

How a single document — and a disciplined agent workflow around it — changed the way our engineers ship code with AI

Why Every New Developer Starts from Scratch in an Agentic Development Ecosystem

Every engineering team adopting AI coding assistants eventually runs into the same wall. A developer opens a chat, explains the codebase from scratch, gets a change, ships it, and closes the tab. The next developer, or the next AI session, starts over. None of that hard-won context survives.

At Acceldata too, the symptoms were familiar: context stayed trapped in one engineer's head and chat history, every task and every agent rediscovered the codebase from scratch, learnings vanished the moment a session ended, and the quality of the output depended entirely on who happened to be doing the prompting.

We decided the fix wasn't a better prompt. It was a better system.

The Core Idea: One Map the Agent Always Reads First

We built our AI-assisted development process around a single artifact: an architecture README.md that acts as the system map for the entire codebase. Before an agent writes a single line of code, it reads this map. The map lays out the module boundaries (for example, which layer owns business logic versus which layer only talks to the database), a recommended reading order through the codebase, cross-references that point straight to code entry points, and rules for which docs need updating when a given area of code changes.

The framework never lets an agent proceed blind. The map is built first, and everything else - the workflow skill, the per-area documentation, hangs off it.

After the agent finishes a task, it writes what it learned back into that same map. That's the loop that makes the whole system compound: explore, plan, code, and test a change; the change starts from a smarter map than the last one; the agent writes its learnings back; and the next change starts even smarter than this one did. Knowledge accumulates instead of evaporating.

Architecture: two directories, one entry point

The whole thing lives in two top-level folders plus two thin editor-integration shims:

Two implementation details matter if you're replicating this:

1. studio/ is editor-agnostic. .cursor/ and .claude/ both just point at it. You write the workflow once; Cursor and Claude Code pick it up identically. This avoids the classic failure of maintaining two divergent prompt/rules files per editor.
2. dev is the only skill loaded unconditionally. The persona skills (principal-engineer, principal-architect, devops) are loaded conditionally, based on what phase 0 determines the task actually is. This keeps the context window lean — you're not stuffing an architect persona and a devops persona into context for a one-line bug fix.

The Core Artifact: architecture/README.md

This is the file the agent is contractually required to read before phase 1 starts. It is not free-form documentation — it has a specific schema with five required sections:

The last row is doing important work: it's an explicit decision rule that prevents the agent from either skipping documentation updates it should make, or pointlessly editing docs for changes that don't warrant it.

Build this file first, before adopting the rest of the workflow. The dev skill assumes it exists and is accurate — it does not have a fallback path for "proceed without a map."

The Workflow: dev skill - Phases 0–8

Invocation is a single slash command:

$ /dev <describe your task> 

This loads studio/commands/dev.md, which loads the dev skill — the single source of truth that drives the agent through a fixed phase sequence with gates at the transitions. At a high level the phases collapse into three stages:

• Understand — Phase 0 reads architecture/README.md, resolves which area docs are relevant via the code-area mapping, and determines task type (bug fix / enhancement / new feature / infra), which in turn determines which persona skill — principal-engineer, principal-architect, or devops — gets pulled into context for the build phase.
• Build — explore → plan → code → test, with the plan presented back to a human for confirmation before any code is written. This is a hard gate, not a suggestion: the workflow is explicitly designed so a human stays in control of scope before generation starts.
• Ship — a test is required for every changed file and must pass before the change is considered mergeable. This is enforced via the reference skill, which holds the actual lint/test commands the gate invokes.

The task-sizing step in phase 0 matters operationally: it's what prevents a one-line config change from triggering a full persona-loaded, multi-phase flow, and what prevents a multi-module feature from being treated like a trivial edit. Size the task before deciding how much process to apply to it.

The Loop that Makes it Compound

The mechanism that distinguishes this from "a good README" is the write-back step. Every cycle is:

context → plan → code → test → ship → write learnings back

The agent doesn't just consume architecture/README.md — the terminal phase of the flow writes updates back into the relevant area doc per the doc-update rule defined in the index. The next /dev invocation on a related area starts from that updated map. Concretely: a change starts smarter because the map already reflects the last change → the workflow writes its own learnings back → the next change starts smarter still. This is the actual compounding mechanism — it's a property of the write-back gate existing, not of using an LLM with a large context window.

Take a look at how context programming works in the video below:

The Results You Can Expect

• Lower blast-radius surprises — because the module map encodes cross-layer boundaries explicitly, an agent generating a change for module A can see what module A is not allowed to touch, and what depends on it.
• Lower token spend per session — enhancements and new features reuse the core design already captured in the map instead of re-scanning the codebase from zero each time. This is a direct cost lever if you're paying per-token for agent runs at scale.
• Hard test gate, not a CI-only check — the requirement is enforced as part of the workflow phase, before the change is considered "done," not just at PR time.
• Process parity across humans and agents — because both Cursor and Claude Code load the same studio/ source, and personas are pulled in by task type rather than by who's driving, PR shape is more consistent regardless of who (or what) authored the change.
• Bounded persona context — loading principal-engineer / principal-architect / devops conditionally rather than always keeps each session's context window focused on the relevant expertise.

None of this required a smarter model. It required treating context the way we already treat code: version-controlled, schema-enforced, and updated as part of the workflow rather than left to memory.

The architecture map makes "the agent should understand our codebase" a hard requirement, not a hope: it's read before any code is written, and updated after every change, with clear rules for what counts as an update. The gates do the same for safety: a human signs off on the plan before code gets written, and tests have to pass before anything merges. Take away the AI framing and this is just standard engineering practice, specs before code, tests before merge, docs that stay current, applied to a new kind of teammate.

The part worth replicating isn't the specific phase count or folder names. It's the structural decision underneath all of it: every session should leave the system smarter than it found it, and that has to be enforced by the workflow, not requested in the prompt. If your team is hitting the same wall — agents re-deriving the same architecture every session, knowledge dying in chat history — the fix is the same one we used: stop trying to write a better prompt, and build the map your agents can't skip.

This is the first of many deep dives we'll be publishing from the engineers actually building these systems day to day, the people wrestling with agent workflows, architecture decisions, and the messy realities of shipping AI-assisted code at scale. If you want to know more about how we're building this, or you're interested in collaborating with our engineering team, reach out to us at engineering.acceldata.io.

And if you don't want to miss what's next, subscribe to get new blogs every week.