← Writing
Project Release · 5 min read · Mar 2026

Why I built archway

Note: archway has since been renamed to verikt. The content below reflects the original project name at the time of writing.

I didn’t set out to build an architecture tool. I set out to understand why AI agents keep making structural decisions without understanding the architecture.

Not broken code. Working code. Code that compiles, passes tests, and is structurally wrong. Business logic in the HTTP handler. No circuit breaker on the payment gateway. A write endpoint with no idempotency. Silent decisions about things that matter — auth model, tenant isolation, error handling strategy — made without a second thought and never documented.

I’d fix it. Next session, same mistakes. The context was gone.

The pattern I kept seeing

Every agent I worked with had the same three problems. They could write correct code, but they couldn’t answer: Where does this code go? What patterns does this codebase already use? What’s missing that should be here?

The third one is the hardest. An agent will never add a circuit breaker to an HTTP client unless something tells it to think about resilience. It will never flag that your retry logic creates duplicates without idempotency unless it knows that’s a risk.

I spent months assuming this was a model problem. Better models would make better architectural decisions. I was wrong.

It’s a context problem

I ran experiments. Took the same codebase, same task, same model. One agent got a one-page architecture guide. The other got nothing.

The results weren’t subtle.

On a real invoicing service — 65 Go files, Kafka consumers, MySQL, external gateways — I gave both agents the same prompt: “Add a handler for refund events. Store it in the database.”

Without the guide, the agent read the simplest handler in the codebase and copied that pattern. Direct typed envelope, no version dispatch, one test case. It used uint64 for the invoice ID when the rest of the codebase uses strings. It never mentioned that refunds are financial operations that need an audit trail.

With the guide, the agent studied the complex handlers, implemented version dispatch with a proper switch statement, wrote four tests including idempotency verification, and flagged the missing audit trail as a compliance gap it couldn’t fix because the infrastructure doesn’t exist yet.

Same model. Same prompt. Same codebase. 40% vs 100% quality score.

The guide cost 45% more tokens. It was worth every one.

But here’s what caught me off guard — on some experiments, the guide had zero or negative impact. Pattern-following tasks, refactors, cross-cutting concerns on Sonnet. When the codebase already has clear patterns and the task is “do more of the same,” the guide is overhead. The codebase itself is the guide.

The guide only matters when the task requires decisions the codebase doesn’t already answer.

What I built

archway is a Go CLI. Four pillars: Guide, Compose, Analyze, Enforce.

archway new composes a production-ready service. An interactive wizard walks you through architecture choice (hexagonal, flat, layered, or clean), then suggests capabilities based on what you’ve picked. “You have an HTTP API but no health endpoint.” “You have retry but no idempotency — that causes duplicates.” It scaffolds the full project with 63 capabilities across 10 categories: transport, messaging, data, security, integration, design patterns, testing, DevOps, architecture, and language.

archway guide is the one that matters most. It reads your project config and generates architecture instruction files — markdown dropped into .claude/rules/, .cursorrules, .github/copilot-instructions.md, .windsurfrules. One command, every AI tool in your stack gets the same context.

The generated guide has three sections that drive the quality improvement:

Smart suggestions — “If you have an HTTP client, you probably need a circuit breaker.” Not a rule. A suggestion with a reason.

Interaction warnings with severity tiers — “Retry without idempotency causes DUPLICATE operations” is a MUST. “HTTP API without health endpoints” is a SHOULD. The agent knows which ones to implement and which ones to flag.

A verification checklist — before the agent finishes, it confirms each item. The ones it didn’t implement, it has to say why. This is what turns silent defaults into explicit decisions.

archway analyze reads your codebase and detects what’s installed. archway check runs 11 AST-based detectors — dependency violations, structural violations, function complexity, and anti-patterns like fat handlers, swallowed errors, or domain layers importing adapters.

What ships in v1

  • 4 architecture patterns: hexagonal, flat, layered, and clean
  • 63 capabilities across 10 categories
  • Smart wizard with 18 suggestion rules and capability interaction warnings
  • 11 AST-based anti-pattern detectors (fat handlers, swallowed errors, domain importing adapters, and more)
  • Guide output to Claude Code, Cursor, GitHub Copilot, and Windsurf
  • archway add for adding capabilities to existing projects
  • archway diff for detecting architectural drift
  • Go today. More languages coming.
go install github.com/dcsg/archway/cmd/archway@latest
archway new

Where this is going

A feature-flag template engine so capabilities adapt to your Go version. TypeScript as the second language provider, with a Rust analysis engine underneath for cross-language rules.

The long play is archway guide as the entry point. One command that feeds architecture context to every AI tool in the org. The CLI is free and always will be. The value compounds as teams scale.

Where to find it

GitHub: github.com/dcsg/archway

Install, run archway new, then run archway guide. Open your next Claude Code session and watch the difference.

Next post: I’ll publish the full experiment data — every prompt, every score, every token count. The guide doesn’t always help. Knowing when is the entire game.