My usual workflow with Claude Code starts with a fairly unstructured list of requirements. I ask it to explore the codebase and write an implementation plan. Before it starts writing code, I ask for diagrams based on the questions I still have. For changes to an existing system, I usually ask for an as-is and to-be view. For a new program, I first check the high-level architecture, then look at the data flow separately. If a component has a complicated lifecycle, I ask for a sequence or state diagram focused on that part. Once the structure is visible, I can correct a component or an arrow instead of explaining the entire system again in prose. Mermaid may be the biggest token saver in this workflow. I also find it convenient for sharing. I send a screenshot when someone only needs to view the diagram, and the Mermaid source when it may need to be changed or reused. The remaining problem is keeping diagrams from becoming stale. If a diagram matters beyond the current task, I keep it in the repository and reference it from the agent instructions so future sessions are more likely to read and update it. I wrote up the workflow and compared a few recent diagram tools here: https://nooker.app/@tim/how-diagrams-fit-into-coding-agent-workflows Disclosure: I built FlowPeek, one of the tools mentioned in the article. The broader workflow predates the tool. What kinds of diagrams do you find most useful before letting Claude Code implement a plan? submitted by /u/Selene_hyun
Originally posted by u/Selene_hyun on r/ClaudeCode