update
Apr 27, 2026
By Teun
Archik stores architecture diagrams in YAML for Claude Code
If you build agent workflows or self-hosted tooling, treat your architecture map as a first-class file in the repo, not a separate drawing. Put a validation...
Archik is a small tool that stores architecture diagrams in YAML, so the diagram lives in the repository alongside the code instead of in a separate drawing file. According to the project’s HN Show HN post, it is meant for Claude Code, with the goal of making architecture a first-class file that agents can read and validate before they touch the system.
That matters because agent workflows often fail in a very specific way, the model updates code that looks correct locally but no longer matches the real service layout. If the architecture map is separate from the repo, it can drift quickly, especially when teams add queues, services, or routing logic without updating the diagram. Archik’s approach is to turn that map into something the tooling can check, not just something humans review.
⚡ New to this?
Archik is a tool that keeps an architecture diagram in YAML, which is a plain text format that machines and people can both read. Instead of storing the diagram in a separate drawing, it puts the system map in the repo so agents like Claude Code can inspect it and compare it with the code. That matters because when the diagram and the code drift apart, automation can make changes in the wrong place.
🦞 OpenClaw angle
If you run self-hosted agents, put your architecture map in version control and make it part of CI, not a side document. Have the agent read that file before editing service boundaries, queues, or routing, and fail the build if new components appear without matching YAML or directory changes. Add a drift check to every merge request so your automation cannot quietly create architecture that the repo never recorded.
The summary for the project points to a validation step in CI, which is the automated check that runs before changes are accepted. In practice, that means structural changes can fail fast when the YAML diagram and the code disagree. For teams running self-hosted agents, that kind of guardrail is often more useful than a polished diagram, because it catches mismatch at the point where the repo changes, not after deployment.
The repo also includes a check command, according to the summary, which is used as a drift test. Drift is just the gap between what the documentation says and what the code actually does. Here, the idea is that the agent should not be able to add new components unless the source directories or YAML are updated to match.
For anyone using Claude Code or a similar coding agent, the practical shift is simple. Feed the architecture spec to the agent before it edits infrastructure, service boundaries, or message paths, then make that spec part of the same review and validation flow as the code. That gives you one source of truth the agent can consult, and one place where broken assumptions can be caught automatically.
The project page on GitHub is the concrete next step, and the useful detail to watch is how the YAML schema and the validation command are structured. If Archik fits your workflow, the repo becomes the place where architecture changes are proposed, checked, and versioned together with the code.
