For Engineers

The agent writes correct syntax. It doesn’t know you use hexagonal architecture, that domain logic belongs in its own layer, or that every outbound call needs a circuit breaker. It puts code where its training data says code goes — not where your architecture says it goes.

You spend the first 10 minutes of every session re-explaining the same things. Or you skip it, and spend the next hour fixing what it got wrong.

Agentic engineering — writing software by orchestrating AI agents rather than authoring every line — has an unsolved infrastructure problem: agents don’t persist context between sessions. Every session starts cold. Your architecture doesn’t.

Osmani puts it directly: agentic engineering disproportionately benefits engineers who already understand the architecture deeply. It amplifies what you know. If that knowledge isn’t encoded somewhere the agent can read, it doesn’t get amplified — it gets lost every session.

The problem with manual context files

Manual .cursorrules and CLAUDE.md files work until they don’t. You write them once, the architecture evolves, and the files don’t. Three months later the agent follows rules that no longer match your codebase.

verikt generates them from verikt.yaml — the same file that drives scaffolding and enforcement. When you add a capability or change your architecture, run verikt guide and every context file updates. The source of truth is the code, not documentation that drifts.

What verikt does

verikt guide reads your verikt.yaml and generates architecture context files for every AI agent you use — Claude Code, Cursor, GitHub Copilot, Windsurf. One command. Every session starts with your architecture already loaded.

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)

The generated files tell the agent your architecture pattern, your layer boundaries, your capability stack, your dependency rules, your naming conventions. What used to live in your head — or in a CLAUDE.md you updated once and forgot — is now always current and always loaded.

The workflow

Run verikt guide once. Then open your agent and prompt naturally — no architectural preamble, no re-explaining layer boundaries.

verikt guide          # generates context for all agents
# open Claude Code / Cursor / Copilot / Windsurf
# start prompting

If you want the agent to surface canonical prompts inside the session itself, use prompted guide mode in your verikt.yaml:

guide:
  mode: prompted

With prompted mode, the generated context file includes a Suggested Prompts section — copy-paste queries the agent understands immediately because the architecture context is already loaded.

The prompts that just work

These are the prompts you write in your agent session. The agent already knows your architecture — you describe the work, not the structure.

You prompt	The agent already knows
Add a GET /orders?customer_id= endpoint. Query by customer ID, return paginated results with RFC 7807 errors, follow our existing repository pattern.	Agent places the handler in the right layer, uses your error format, wires the router correctly — without being told where anything goes.
Here's the PRD for the order history feature [paste]. Implement the API endpoints in section 3.	Agent reads the spec, maps requirements to your declared architecture, produces implementation that fits existing patterns — placement, boundaries, capabilities all correct.
What capabilities am I missing before going to production?	Agent cross-references installed capabilities against smart suggestion rules — flags missing health, request-id, observability if http-api is present.
I need to add payments — what do I need?	Agent identifies idempotency and audit-log as required, explains why, suggests `verikt add idempotency audit-log`.
Walk me through this codebase.	Agent explains the architecture, layer boundaries, and capability set from the guide — not from guessing based on file structure.
Where should I put this logic?	Agent answers based on your declared architecture — domain, service, adapter, handler — without you having to explain the pattern.
Review this PR for architecture violations before I submit it.	Agent runs `verikt check --diff main`, surfaces violations before the PR is opened — not after.
I just added kafka, update the architecture context.	Agent runs `verikt add kafka-consumer && verikt guide` — context updated in one step.

Starting a new service

If you’re greenfield, use verikt init --ai to let your agent handle the entire setup — no TUI, no context switch:

verikt init --ai

This prints an interview protocol to stdout. Paste it into your agent. The agent interviews you — service name, architecture pattern, capabilities — then runs verikt new and generates context files. The whole setup happens inside your agent session.

verikt guide runs automatically after scaffold. By the time the agent finishes setup, it already has the architecture context loaded for the next prompt.

Working with existing services

verikt analyze detects your architecture pattern in an existing codebase and generates an verikt.yaml. Then run verikt guide to generate context files.

verikt analyze        # detects architecture, generates verikt.yaml
verikt guide          # generates agent context from verikt.yaml
verikt check          # run enforcement against current codebase

verikt check uses 11 AST-based detectors — wrong-layer dependencies, missing capabilities, pattern violations. Run it locally before pushing, or in CI on every PR.

Get started

brew install diktahq/tap/verikt
verikt init --ai      # let your agent set up the project
verikt guide          # or run directly if you have an existing verikt.yaml

→ Quick Start with AI Agents — full walkthrough of the agent-first workflow → Prompt Engineering guide — how to write prompts that get architecture-correct output → For Engineering Leaders — how this scales to team consistency and CI enforcement