Aylon, the founder of ArchDocs, has emerged from the Hacker News shadows to present a solution for the fragmentation of engineering context in the AI era. Launched initially in late 2024 as an architecture diagramming tool, ArchDocs has evolved into a shared verification layer that forces coding agents and human engineers to operate from the same source of truth. The core premise is simple but critical: agents should not guess at system architecture; they should read it, ask questions, and verify their work against recorded plans.

The MCP Bridge For Agent Context

ArchDocs leverages the Model Context Protocol (MCP) to bridge the gap between static documentation and dynamic agent workflows. By connecting to https://mcp.archdocs.io/mcp, agents using tools like Claude, Cursor, and VS Code can read architecture docs, write design decisions, and record changes in real time. Crucially, the system instructs agents to ask for clarification on open questions rather than making assumptions. This prevents the common failure mode where an agent confidently implements a feature that contradicts an unspoken architectural constraint.

Verification Over Assumption

The platform introduces a rigorous 'Plan versus Recorded' verification system. When an agent or human marks a task as complete, ArchDocs compares this against the approved design doc and checks for corresponding GitHub pull requests or code changes. If an agent claims to have updated a service but no code change is detected in the linked repository, the system flags it as 'Planned; no recorded change.' This audit trail ensures that agent-generated code is not just syntactically correct, but architecturally aligned with the team’s intent.

Shared Objects And Single Source Of Truth

At the foundational level, ArchDocs enforces the definition of services, queues, and databases as reusable 'objects.' A change to a service definition, such as updating a database engine from PostgreSQL 16 to 17, automatically propagates through all linked diagrams and design docs. This eliminates the drift between documentation and reality, providing agents with a stable, version-controlled view of the system. The diagrams themselves are stored as YAML, allowing for Git-based review and ensuring that the architecture remains a first-class citizen in the development workflow.

Key Takeaways

  • ArchDocs uses MCP to provide coding agents with live access to architecture and design docs.
  • The platform enforces a 'Plan vs. Recorded' verification step to catch agent hallucinations or incomplete implementations.
  • Shared objects ensure that architectural changes propagate automatically across all documentation and agent contexts.
  • Agents are explicitly instructed to ask humans about open questions rather than making unilateral decisions.

The Bottom Line

For teams drowning in agent-generated code, ArchDocs offers a necessary guardrail: if the agent can’t prove it followed the plan, it didn’t do the job. This is the infrastructure we need to trust AI in production systems.