verikt guide

Overview

verikt guide reads your project’s verikt.yaml and generates architecture context that AI coding agents can consume. Instead of fixing architecture violations after the fact, feed your agent the rules upfront.

Prevention beats correction.

verikt guide [flags]

Flags

Flag	Description	Default
--target	AI tool target (all, claude, cursor, copilot, windsurf)	all
--path	Path to project	.
--output	Output format (terminal, file)	terminal

Usage

Default (any AI agent)

verikt guide

Outputs architecture context to stdout — paste it into any AI chat or system prompt.

Claude Code

verikt guide --target claude

Generates context optimized for Claude Code’s CLAUDE.md format.

Cursor

verikt guide --target cursor

Generates context for Cursor’s .cursorrules format.

Copilot

verikt guide --target copilot

Windsurf

verikt guide --target windsurf

Example Output

# Architecture: hexagonal
# Components: domain, port, service, adapter

## Dependency Rules
- domain/ must NOT import from port/, service/, adapter/
- port/ must NOT import from service/, adapter/
- service/ must NOT import from adapter/

## Capabilities
- http-api: REST API with Chi router, RFC 7807 errors
- mysql: MySQL with connection pooling
- platform: Config, structured logging, graceful shutdown

## Anti-patterns to Avoid
- No SQL string concatenation (use parameterized queries)
- No domain importing adapters
- No fat HTTP handlers (delegate to service layer)
- No global mutable state

Tip

Run verikt guide in your project root — it reads verikt.yaml to generate context specific to your project’s architecture and capabilities.

Governance Checkpoint

Every guide output includes a governance checkpoint — an instruction block that tells agents to verify architecture rules at two points: before modifying any file, and after receiving tool results (test output, build errors, lint output).

The checkpoint doesn’t add new rules. It tells the agent when to check the rules that are already in the guide. The prompting pattern comes from Anthropic’s think tool research, which found that agents follow complex policies significantly better when explicitly told to pause and verify at decision points rather than only receiving the rules upfront.

In EXP-10, the checkpoint eliminated variance in agent compliance (0.89 → 0.00) and reduced violations by 25% on greenfield builds. On brownfield projects with a conforming codebase, the checkpoint has no measurable effect — the existing code already constrains the agent.

The checkpoint adds approximately 80 tokens to the guide output. It appears in all target formats (Claude, Cursor, Copilot, Windsurf).

Supported AI Tools

Tool	Target Flag	Output File
All tools	--target all (default)	All files below
Claude Code	--target claude	.claude/rules/verikt.md
Cursor	--target cursor	.cursorrules
GitHub Copilot	--target copilot	.github/copilot-instructions.md
Windsurf	--target windsurf	.windsurfrules