For Engineering Leaders

Every PR review is an architecture conversation it shouldn’t be.

An engineer on your team uses Cursor to add a feature. The code works. The tests pass. But the domain logic is in the handler, the repository is called directly from the service layer, and there’s no circuit breaker on the new external call. You catch it in code review. You explain the architecture — again. The engineer fixes it, the PR ships a day later.

Multiply that by five engineers, all using different agents, all starting every session cold.

The team-scale problem

Individual engineers feel the pain as wasted time. You feel it as compounding inconsistency. When everyone’s agent is working from training data patterns instead of your architecture, every PR becomes an opportunity for drift. The reviewers become the architecture enforcers — catching violations at the most expensive point in the development cycle.

This compounds as the team adopts AI agents faster. O’Reilly’s analysis of the shift from individual agents to parallel multi-agent workflows makes the stakes concrete: “shared context, memory, and smooth transitions” become required infrastructure — without it, each agent becomes an isolated silo. The architecture problem doesn’t shrink as you add more agents. It scales with them.

Teams with high AI adoption merge 98% more PRs — but review times balloon by 91%. Only 48% of developers consistently check AI-assisted code before committing. (Osmani, The 80% Problem.) The productivity gain lands in generation. The cost lands in review. Architecture violations caught in code review are the most expensive version of that cost.

What verikt does

verikt guide generates architecture context files from your verikt.yaml — one source of truth that covers every AI agent your team uses (Claude Code, Cursor, GitHub Copilot, Windsurf). Every engineer runs verikt guide and their agent starts with your architecture already loaded.

The files tell the agent: the architecture pattern (hexagonal, clean, layered), the layer boundaries, the capability stack, the dependency rules, the naming conventions. What used to live in a wiki page nobody reads is now in a file every agent reads automatically.

verikt guide
# Generated .claude/rules/verikt.md (1,247 tokens)
# Generated .cursorrules (1,247 tokens)
# Generated .github/copilot-instructions.md (1,247 tokens)
# Generated .windsurfrules (1,247 tokens)

Enforcement in CI

verikt check runs architecture enforcement using 11 AST-based detectors. Wrong-layer dependencies, missing capabilities, capability interaction violations. It runs in your CI pipeline on every PR — the violations are caught before review, not during it.

# GitHub Actions
- name: Architecture check
  run: verikt check --diff   # only files changed in this PR

Reviewers stop catching architecture violations. They review business logic.

Tip

verikt check --diff only analyses files changed in a given PR. Suitable for teams with existing codebases — no need to clean up the entire repo before adopting it.

One source of truth

The most common failure mode of manual context files (CLAUDE.md, .cursorrules) is staleness. Written once, updated never, irrelevant within months.

verikt generates context from verikt.yaml — the same file that drives scaffolding and enforcement. When the architecture evolves, you update verikt.yaml and run verikt guide. Every agent context file across your team updates. No wiki page to maintain, no CLAUDE.md to remember to update.

For existing codebases

verikt analyze detects your architecture pattern in an existing service and generates an verikt.yaml. No greenfield requirement.

verikt analyze          # detects architecture, generates verikt.yaml
verikt guide            # generate context for all agents
verikt check            # run enforcement against current codebase

For teams adopting verikt mid-flight: start with one service, run verikt analyze, generate context files, run check in non-blocking mode first to understand the baseline. Tighten from there.

What the team adopts

verikt is a CLI. Engineers install it, run three commands, and their agents get architecture context. No login, no dashboard, no onboarding call. The time-to-value is under 5 minutes.

Team adoption happens organically — one engineer adopts it, their PRs stop triggering architecture conversations, others notice. You don’t need to mandate it to see it spread.

Get started

brew install diktahq/tap/verikt
verikt guide

One engineer. Five minutes. Their next agent session starts with your architecture already loaded.

→ Quick Start with AI Agents — the full walkthrough for each engineer → CI Integration guide — how to add verikt check to your pipeline → For Engineers — the engineer’s perspective on the same problem