Quick Start with AI Agents

Every time you open a new AI coding session, the agent starts cold. It doesn’t know your architecture, your layer boundaries, or which capabilities you’ve wired. So you explain it. Every session. Or the agent puts things in the wrong place and you spend time correcting it.

verikt guide fixes this permanently.

Install

# Homebrew (recommended)
brew install diktahq/tap/verikt

# Install script (macOS/Linux)
curl -sSL https://verikt.dev/install.sh | bash

The Workflow

Tip

Existing project? Skip step 1 — go straight to step 2. Run verikt analyze first if you don’t have an verikt.yaml yet.

1. Let your AI agent set up the project

   Run this once in your terminal:

   verikt init --ai

   This prints the AI interview protocol to stdout. Paste it into your AI agent. The agent will interview you — asking about your service name, architecture, capabilities, and guide mode — then run verikt new and generate everything.

   No TUI. No switching context. The whole setup happens inside your AI session.

2. Generate architecture context

   verikt guide

   verikt reads your verikt.yaml and generates context files for every supported AI agent — directly in your project.

   Claude Code .claude/rules/verikt.md

   Cursor .cursorrules

   GitHub Copilot .github/copilot-instructions.md

   Windsurf .windsurfrules

3. Open your agent and start prompting

   Pick your tool and follow the steps for it:

   Claude Code

   Claude Code reads .claude/rules/verikt.md automatically on every session start. No setup needed beyond running verikt guide.

   Open Claude Code in your project directory:

   cd your-project
   claude

   Write prompts naturally — no preamble, no context-setting:

   Add a new endpoint to list orders by customer ID

   The agent already knows your layer boundaries, your error format, and which capabilities you have installed.

   Commit the generated file so every engineer on the team gets the same context:

   git add .claude/rules/verikt.md
   git commit -m "chore: add verikt architecture context"

   Re-run verikt guide whenever you add capabilities or change your architecture. The file updates automatically.

   Cursor

   Cursor reads .cursorrules automatically when you open the project folder. No setup needed beyond running verikt guide.

   1. Open Cursor
   2. File → Open Folder → select your project directory
   3. Open the chat panel (Cmd+L)

   Write prompts naturally — no preamble, no context-setting:

   Add a new endpoint to list orders by customer ID

   The agent already knows your layer boundaries, your error format, and which capabilities you have installed.

   Commit the generated file so every engineer on the team gets the same context:

   git add .cursorrules
   git commit -m "chore: add verikt architecture context"

   Re-run verikt guide whenever you add capabilities or change your architecture. The file updates automatically.

   GitHub Copilot

   GitHub Copilot reads .github/copilot-instructions.md automatically. The steps differ slightly between VS Code and JetBrains.

   VS Code:

   1. Install the GitHub Copilot extension
   2. Open your project (File → Open Folder)
   3. Open Copilot Chat (Cmd+Shift+I)
   4. Prefix your prompt with @workspace — this tells Copilot to index the project files including .github/copilot-instructions.md:

   @workspace Add a new endpoint to list orders by customer ID

   JetBrains (IntelliJ, GoLand):

   1. Install the GitHub Copilot plugin (Settings → Plugins → search "GitHub Copilot")
   2. Open your project
   3. Open Copilot Chat (Tools → GitHub Copilot → Open Chat)
   4. Write prompts naturally — no prefix needed in JetBrains:

   Add a new endpoint to list orders by customer ID

   The agent already knows your layer boundaries, your error format, and which capabilities you have installed.

   Commit the generated file so every engineer on the team gets the same context:

   git add .github/copilot-instructions.md
   git commit -m "chore: add verikt architecture context"

   Re-run verikt guide whenever you add capabilities or change your architecture. The file updates automatically.

   Windsurf

   Windsurf reads .windsurfrules automatically when you open the project folder. No setup needed beyond running verikt guide.

   1. Open Windsurf
   2. File → Open Folder → select your project directory
   3. Open the Cascade panel (right side)

   Write prompts naturally — no preamble, no context-setting:

   Add a new endpoint to list orders by customer ID

   The agent already knows your layer boundaries, your error format, and which capabilities you have installed.

   Commit the generated file so every engineer on the team gets the same context:

   git add .windsurfrules
   git commit -m "chore: add verikt architecture context"

   Re-run verikt guide whenever you add capabilities or change your architecture. The file updates automatically.

   Other

   For any other AI tool (Zed, Aider, Continue, raw API, etc.), verikt guide still generates all context files. Use .cursorrules — it’s plain markdown and works as a starting point for any tool.

   verikt guide

   This generates .cursorrules (among others) — a self-contained markdown file with your full architecture context: layer boundaries, capability stack, dependency rules, and interaction warnings.

   Since your tool has no auto-loading, you need to include the context manually each session:

   Option A — paste at session start:

   Copy the contents of .cursorrules and paste it as your first message or system prompt before asking anything:

   [paste contents of .cursorrules here]
   
   Now: add a new endpoint to list orders by customer ID

   Option B — file reference (if your tool supports it):

   If your tool supports referencing files as context (Aider, Continue, etc.), point it at .cursorrules:

   # Aider example
   aider --read .cursorrules
   
   # Continue — add .cursorrules to your context window via the @ file picker

   There is no automatic loading for unsupported tools. For automatic context injection without manual steps, use Claude Code, Cursor, GitHub Copilot, or Windsurf.

What the Agent Gets

The generated file gives the agent four things it would otherwise ask you for:

• Capability catalog — what’s installed and what’s available but not yet added.
• Dependency rules — if you have http-api, the agent knows you probably need health, request-id, and validation, and flags those gaps proactively.
• Interaction warnings — dangerous combinations like retry without idempotency are surfaced before you ship a duplicate payment bug.
• Dependency graph — which layers exist, what they’re allowed to import, and what a violation looks like.

How the Agent Responds

The generated context file tells the agent to research first, architecture notes last:

1. The agent searches the web for current docs, reads your codebase, and answers your question fully.
2. At the end of its response, it appends an ## Architecture Notes section with any gaps, warnings, or violations that apply. If nothing applies, the section is omitted.

For a prompt like “I need to handle payments”, you get a complete answer — Stripe integration, webhook verification, error handling — followed by:

## Architecture Notes
- ⚠️  Missing `idempotency` — payment operations must be safe to retry.
  Run: verikt add idempotency
- ⚠️  Missing `audit-log` — financial mutations require an append-only audit trail.
  Run: verikt add audit-log
- ✓  `circuit-breaker` is installed — wire it to your Stripe HTTP client.

Then you add the missing capabilities and re-run guide:

verikt add idempotency audit-log
verikt guide

The agent now knows how all of them are wired.

Keeping Context Fresh

Re-run verikt guide whenever your architecture changes:

# After adding capabilities
verikt add kafka-consumer
verikt guide

# After changing verikt.yaml manually
verikt guide

Guide Modes

Configure how AI agents use the architecture guide in your verikt.yaml:

guide:
  mode: passive   # passive | audit | prompted

The wizard asks for this when you run verikt new.

passive (default)

The agent answers your question fully — searching the web, reading the codebase — then appends an ## Architecture Notes section at the end if anything applies.

Best for: day-to-day coding. Low friction, always on.

audit

On every session start, the agent reads the codebase, cross-references it against verikt.yaml, and leads with an ## Architecture Audit section listing violations, missing capabilities, and drift — before answering any question.

Best for: onboarding a new service, pre-release review, team handoffs.

prompted

Same as passive, but the generated guide file includes a Suggested Prompts section at the bottom — copy-paste queries that unlock the most value from verikt:

Audit this codebase against verikt.yaml and list all violations
What capabilities am I missing before going to production?
I need to add [feature] — what capabilities do I need and how should I wire them?
What dangerous capability combinations do I have that need fixing?

Best for: teams new to verikt, or when you want to teach others what to ask.

---

• Capabilities Matrix — all capabilities across 10 categories
• How It Works — the composition model behind verikt
• Quick Start with CLI — prefer the terminal wizard? start here