「コードは読まない」開発スタイル ― Mermaid図解とモジュール分割で人間とAIの分業を作るThe author describes a workflow where humans focus on intent and diagrams while…

As AI coding agents grow capable enough to write and maintain large portions of a codebase, some developers are rethinking which artifacts humans should actually spend their attention on. In a blog post published on Zenn, one developer describes arriving at a deliberate division of labor while building with Claude Code alongside a real-time voice AI system: humans do not read the code. Instead, the AI reads and manages the code, while people hold the diagrams and the intent behind them.

The author frames this as a practical concession rather than a universal law. The reasoning is that once an AI agent handles the bulk of implementation, a human's time is better invested in describing what the system should do and how its parts relate, rather than parsing line-by-line syntax. In that model, the diagram becomes the primary human-facing representation of the system, and natural-language intent becomes the specification the AI works against. The code itself is treated as an output that the machine both produces and consumes.

A notable detail in the account is the choice of diagramming tool. When the author asked the AI to draw the system's mechanics in UML, explicitly noting an unwillingness to read code, the suggestion was Mermaid rather than draw.io. Mermaid is a text-based diagramming syntax, whereas draw.io (also known as diagrams.net) is a graphical, canvas-driven editor. The author cites three reasons for preferring the text-based approach. First, GitHub automatically renders Mermaid inside README files and other Markdown, so diagrams appear directly where documentation lives. Second, because Mermaid is plain text, changes can be reviewed as diffs in pull requests, the same way source changes are. Third, an AI can generate and update Mermaid directly, which means a diagram can be kept in step with the implementation rather than drifting out of date.

That last point speaks to a recurring problem in software documentation: diagrams drawn in binary or proprietary formats tend to rot because they are expensive to keep current. By expressing architecture as text that lives beside the code, the author is effectively treating diagrams as a first-class, version-controlled asset. If the AI updates both the implementation and the corresponding Mermaid description in the same change set, the diagram can function as living documentation rather than a snapshot taken once and forgotten.

The second pillar the author highlights is module separation. Breaking a system into well-bounded modules appears to serve two purposes in this workflow. It gives the human a clean set of components to reason about at the diagram level, and it gives the AI a smaller, more contained surface area to modify when a change is requested. Clear module boundaries make it easier to map a stated intent onto a specific part of the codebase, which is likely what makes the "humans hold intent, AI holds code" arrangement workable in practice rather than just in theory.

Some background helps situate the piece. Claude Code is Anthropic's command-line coding agent, designed to read a repository, make edits, run commands, and iterate within a developer's terminal. It sits alongside other AI-assisted development tools such as GitHub Copilot, which began as an in-editor autocomplete and has expanded toward agentic, multi-file capabilities, as well as editors like Cursor and various open-source agents. The broader industry direction is toward agents that operate over an entire project rather than suggesting single lines, which is what makes a workflow like this one plausible today when it would have been impractical a few years ago.

It is worth treating the described approach as one practitioner's opinion rather than an established best practice. Choosing not to read code carries clear trade-offs around review, debugging, security, and accountability, and the author's framing suggests this works best within a particular kind of project and tooling setup. Mermaid itself has limits; complex diagrams can become unwieldy in text form, and it does not cover every notation a team might need. The value of the post is less a claim that everyone should stop reading code and more a concrete illustration of how diagrams, module boundaries, and version control can be arranged so that humans and AI agents each work with the representation best suited to them. For teams experimenting with agent-driven development, the emphasis on text-based, reviewable, machine-updatable diagrams offers a pragmatic starting point.