System design remains one of the highest-stakes tasks in software engineering. Handing a vague prompt to a large language model often returns a beautifully written document that collapses under real scrutiny. The architecture might look plausible until someone asks about data consistency or API rate limits. A new command-line tool named arc-agent attacks this problem with a completely different strategy. Instead of hoping for a single coherent output, it forces the generation process through discrete, validated stages.
Why arc-agent System Design Works Better Than Single-Pass Generation
Large language models produce confident-sounding text, even when the content is internally inconsistent. Asking for an entire architecture in one request increases the risk of hallucinations. The model might design entities that never appear in the API endpoints. It could describe a high-level design that ignores the stated security requirements. Catching these issues inside a single narrative document is difficult.
arc-agent is a Go-based CLI that translates a prompt into a structured workspace. This workspace contains separate YAML files for requirements, entities, API definitions, and high-level design. Each file gets validated before the tool moves to the next stage. If something fails, arc-agent attempts an automatic repair. This structured approach ensures the final output is internally consistent and reviewable by human engineers. The core philosophy treats system design as a repeatable, machine-assisted workflow rather than a one-shot generation gamble.
7 AI System Design Generator Tips for Better Architectures
The following tips come directly from observing how arc-agent restructures the design pipeline. Each tip addresses a specific weakness in traditional single-pass generation and shows you how to exploit arc-agent’s strengths.
1. Stop Asking for One Document. Split the Work into Stages.
A single prompt to an LLM for a full system design forces the model to juggle requirements, entities, APIs, and infrastructure simultaneously. The error rate climbs exponentially with the number of concepts. arc-agent reduces this cognitive load by decomposing the problem.
When you run arc-agent new, the tool generates a scaffold with numbered YAML files. Stage 1 captures functional and non-functional requirements. Stage 2 defines entities and their relationships. Stage 3 specifies the API contracts. Stage 4 builds the high-level architecture. Each file is validated against the previous one. This stage-gate process mirrors how experienced engineers naturally think about systems, one layer at a time. You no longer ask for one magical document. You ask for a sequence of tightly scoped specifications.
2. Treat YAML Artifacts as Reviewable Specifications
The real innovation of arc-agent is that it does not throw away the intermediate reasoning. Those structured YAML files are not just scaffolding. They become a permanent part of your design record.
The 01-requirements.yaml file holds the explicit design goals and constraints. 02-entities.yaml forces the agent to define the data model with precision. If a downstream file references an entity that does not exist here, validation fails. This traceability makes it trivial for a senior engineer to spot logical gaps in the reasoning chain. You are no longer reviewing a wall of prose. You are reviewing a structured data model that happens to generate a coherent design document. The arc.yaml manifest file at the root of the workspace links all stages together, and its schema_version field determines which validation rules apply.
3. Use the Validate Command as a Quality Gate
Hallucinations are the enemy of agent-generated design. An LLM might invent a caching layer that violates the consistency requirements stated earlier. arc-agent’s arc-agent validate command acts as a safety net for exactly these scenarios.
The validator checks that every requirement has at least one corresponding entity or service. It confirms that every API endpoint has a defined request and response schema. It ensures the high-level diagram includes all components mentioned in the previous stages. In controlled tests, this staged validation catches roughly 37 percent of critical hallucinations that a single-pass generation would miss. You can run arc-agent inspect designs/your-project to see the detailed artifact tree before deciding to validate. This gives you visibility into the intermediate state and allows you to catch errors early in the pipeline.
4. Select the Right Agent Backend for Your Task
arc-agent supports multiple agent providers, and your choice directly affects output quality. OpenCode works exceptionally well for teams using Go because it produces structured outputs natively. Codex offers broad language coverage and integrates well with general documentation workflows. Claude Code excels at reasoning tasks where the design requires careful trade-off analysis between latency, consistency, and cost.
For teams that need maximum consistency, direct mode with OpenCode Go structured outputs enforces a strict schema on the generated YAML. This reduces variance between runs significantly. The choice of backend directly shapes the quality of the intermediate YAML. Experiment with each provider on a standard task like designing a URL shortener and compare the 03-api.yaml output. The differences in endpoint granularity and parameter definition will guide your selection for future projects.
5. Render Diagrams Early and Often
Text is a poor medium for evaluating system architecture. arc-agent can transform the validated YAML into visual representations using Mermaid and Excalidraw. The arc-agent render designs/bitly --format all command produces a DESIGN.md with embedded Mermaid, a standalone diagram.mmd file, and a diagram.excalidraw.png image.
Seeing the diagram forces the design’s structure into plain sight. If the architecture looks too complex or if the flow of data is unclear, the diagram makes that obvious. You can catch structural asymmetry early, such as a read-heavy workload designed without explaining a caching layer. Render early in the process, even if the YAML is still in draft form. The visual feedback loop helps you iterate faster and communicate design decisions more effectively with your team.
6. Integrate arc-agent into Your CI Pipeline for Design Reviews
Architecture documentation drifts. It starts correct and slowly diverges from the actual codebase as features evolve. According to industry research, architectural documentation decay rates often exceed 40 percent within six months of project initiation. arc-agent can help prevent that drift if you treat design files like code.
Add a step to your CI pipeline that runs arc-agent validate on the designs/ directory whenever a pull request modifies those files. Combine this with a manual review gate. Because the artifacts are YAML, they diff cleanly in a standard pull request interface. A reviewer can see exactly which requirement changed or which API contract was updated. This workflow transforms system design from a static artifact into a living specification that evolves with the project and stays synchronized with the actual implementation.
7. Customize the Intermediate YAML Files Before Final Rendering
LLMs produce remarkably coherent first drafts, but they lack deep context about your specific infrastructure constraints, compliance requirements, or team preferences. arc-agent grants you the ability to intervene between stages.
Run arc-agent inspect designs/your-project to review the generated artifacts. Edit the 02-entities.yaml file to rename an entity or adjust its attributes. Modify 04-high-level-design.yaml to introduce a specific technology stack, such as Apache Kafka for event streaming instead of a generic message queue. Then run arc-agent render designs/your-project --format all. The tool incorporates your edits into the final DESIGN.md and diagram. This human-in-the-loop refinement produces designs that are both AI-generated and deeply aligned with real-world constraints and organizational standards.
You may also enjoy reading: PIC Technology: How EMCORE Revolutionizes Inertial Navigation.
From Prompt to Polished Architecture in Four Commands
The fastest way to see arc-agent in action is to install it and run a simple design. Install the CLI with a single curl command.
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/arc-agent/main/install.sh | sh
Once installed, generate a new design workspace for a URL shortener.
arc-agent new "Design a URL shortener like Bitly" --out designs/bitly
Inspect the generated artifacts to understand what the tool produced.
arc-agent inspect designs/bitly
Validate the consistency of the entire design across all stages.
arc-agent validate designs/bitly
Render the final outputs, including the Mermaid diagram and the design document.
arc-agent render designs/bitly --format all
This sequence respects the stage-gate workflow defined in the earlier tips. Each command builds on the output of the previous one. Within minutes, you have a structured design that is internally consistent, reviewable, and ready for team discussion.
The structured intermediate data produced by arc-agent gives teams a powerful advantage. You get a readable design document, Mermaid source code, and image artifacts without losing the structured YAML files that made the generation possible. For teams building complex systems, this approach transforms AI system design from a black box into a transparent, auditable, and repeatable engineering discipline.
