Streamlining AI Coding Agents with a Workflow Layer: Lessons

As AI‑driven code assistants become more capable, developers are increasingly relying on them to write features, fix bugs, and generate patches. The promise is alluring: a conversational partner that can understand a codebase, suggest implementations, and iterate until the desired outcome is reached. Yet, many practitioners quickly discover a hidden friction point—context loss. When a task grows beyond a handful of exchanges, the agent often forgets earlier decisions, repeats steps, or circles back to the same problem.

In a recent open‑source experiment called Hanesu (available on GitHub), the author tackles this exact pain point by introducing a lightweight workflow layer that sits between the developer, the AI model, and the repository. The goal is simple: give each stage of a development task its own dedicated agent, persist the state of the work, and provide a clear audit trail for future iterations.

This post unpacks the motivation behind Hanesu, how it differs from simply dumping all context into a single Claude or Codex prompt, and why a staged approach can be a game‑changer for complex, token‑heavy tasks.

---

Why a Separate Workflow Layer?

The Context Bottleneck

Large language models (LLMs) such as Claude, Codex, or OpenCode excel at in‑context learning—they can produce code when given a concise description and a few relevant snippets. However, their context windows are finite. As a conversation expands, older messages are pushed out, and the model loses access to critical decisions made earlier in the workflow. The author of Hanesu observed that this leads to:

1. Repeated effort – the agent re‑asks for information it already gathered. 2. Inconsistent state – variables, file changes, or design decisions drift without a single source of truth. 3. Higher token costs – every additional round of dialogue adds to the token count, making large tasks expensive.

The Limits of a Monolithic Prompt

One could argue that a well‑crafted CLAUDE.md file, which outlines the entire development process, should be enough. While CLAUDE.md provides guidelines on how to work, it does not capture the execution state of a specific task. It cannot store which files have been edited, which tests have passed, or which edge cases have been explored. Consequently, the model must reconstruct that state from the conversation each time, a fragile and inefficient process.

---

How Hanesu Works

Stage‑Specific Agents

Hanesu decomposes a development workflow into discrete stages—analysis, implementation, testing, and review. Each stage is handled by a dedicated AI agent that receives only the information relevant to its responsibility. For example:

- Analysis Agent reads the issue description, scans the repository, and produces a high‑level plan. - Implementation Agent receives the plan and a list of target files, then generates code. - Testing Agent runs the test suite (or a simulated one) and reports failures. - Review Agent compares the new changes against the original intent and flags any mismatches.

Because each agent works with a focused context, the token budget is used more efficiently, and the likelihood of the model drifting off‑topic is reduced.

Persistent Task State

After each stage, Hanesu writes a JSON‑encoded task log back into the repository (e.g., .hanesu/state.json). This log records:

- The current step and its outcome. - Files touched and the diffs applied. - Test results and any open questions. - A timestamp and a short human‑readable summary.

When a subsequent stage begins, the agent reads this log, instantly regaining the full history without needing the entire chat transcript. This persistence also creates an audit trail useful for debugging and for future developers who inherit the task.

Leveraging Existing Tools

Hanesu does not reinvent the underlying code‑generation models. Instead, it acts as a thin orchestration layer that calls out to Codex, Claude Code, or OpenCode as needed. The choice of model can be swapped per stage, allowing teams to balance cost, speed, and quality.

---

When to Use Hanesu (and When Not To)

Ideal Scenarios

- Large feature implementations where design decisions span multiple files. - Complex bug investigations that require iterative testing and refactoring. - Team‑wide refactors where a consistent audit trail is essential.

In these cases, the overhead of managing multiple agents and persisting state pays off by reducing redundant iterations and token consumption.

Less Suitable Cases

- Tiny scripts or one‑off fixes – a single prompt is faster and cheaper. - Proof‑of‑concept prototypes where speed trumps reproducibility.

For small tasks, the additional stages of Hanesu may actually increase token usage without delivering a measurable benefit.

---

Reflections from the Creator

The author of Hanesu notes that the system is still experimental. Mistakes happen—agents can still generate incorrect code or misinterpret the task log. However, the recorded state means that a second pass can quickly identify what went wrong and correct it, rather than starting from scratch.

The creator invites community feedback: “Does this approach make sense to you? In my experience it has been useful.” This open invitation underscores the collaborative nature of the project and its reliance on real‑world usage to mature.

---

Key Takeaways

1. Context windows are a hard limit for LLM‑driven development; a workflow layer mitigates this by persisting state. 2. Stage‑specific agents keep each prompt concise, improving relevance and reducing token waste. 3. Task logs provide an immutable history that aids debugging and future hand‑offs. 4. Tool‑agnostic orchestration lets teams pick the best model for each phase without locking into a single provider. 5. Cost‑benefit balance – Hanesu shines on complex, multi‑step tasks but may be overkill for simple fixes.

---

Looking Ahead

As AI coding assistants become more integrated into development pipelines, the need for structured orchestration will grow. Projects like Hanesu hint at a future where AI agents are not just chatty helpers but disciplined collaborators that respect the same workflow conventions humans use.

If you’re interested in experimenting, the source code is openly available on GitHub. Try it on a modest feature branch, observe how the state log evolves, and share your findings with the community. The collective insights will shape the next generation of AI‑augmented development tools.

Happy coding, and may your agents stay in context!

Sources: https://github.com/jezmn/hanesu