AI Agent Guide
How to Use Claude Code with VerdantStack
VerdantStack starters ship with AGENTS.md and generated API references — so Claude Code reads the architecture, respects your invariants, and starts productive from the first prompt. Here's how to use that.
What VerdantStack gives Claude Code
Every starter includes machine-readable context files that Claude Code reads automatically:
AGENTS.md
General-purpose agent context: architecture diagram, file map, commands, and the invariants it must not "fix." Claude Code reads this automatically; other tools (Cursor, Copilot) also read it. This is the file that prevents Claude Code from reinventing your auth system.
TypeDoc API reference
Generated from the compiler — never drifts from the code. Claude Code can read function signatures, types, and parameters for any module.
Step by step
1. Clone the starter and open it in your terminal
Every VerdantStack starter ships with AGENTS.md at the root. Claude Code reads it automatically — no configuration needed. The file contains the architecture diagram, the file map, and the three rules the agent must not break.
2. Let Claude Code read the codebase
Claude Code will scan AGENTS.md on its first turn. It now knows the DB schema (Drizzle), the auth model (scrypt + hashed sessions), the RBAC hierarchy (owner > admin > member), and the service layer. You don't need to explain the architecture — it's already loaded.
3. Ask for features in plain language
Because the agent knows the patterns, you can ask in plain terms: "Add a team invite flow with email notifications" or "Add a new role called editor between admin and member." Claude Code will use the existing service layer, RBAC system, and audit log — not invent a parallel one.
4. Verify with the test suite
After Claude Code generates code, run the test suite: npm test. The 259–314 tests (depending on the starter) are your safety net. If the agent broke an invariant, the tests catch it. This is the difference between "AI-generated code that works" and "AI-generated code you can ship."
5. Use the API reference for deeper context
When you need Claude Code to work with a specific module, point it at the generated TypeDoc API reference. The agent can read function signatures, parameter types, and return values — a spec that never drifts from the code because it's generated by the compiler.
Tips for better results
Start with AGENTS.md
Claude Code reads it automatically. If it's not there, the agent guesses. If it is, the agent starts productive.
Use AGENTS.md for invariants
Put the things that must not change in AGENTS.md. Claude Code treats it as a constraint file — it will not "fix" patterns you've locked down.
Point at the API reference
Instead of "how does the billing adapter work?", say "read the TypeDoc for src/lib/server/billing/index.ts and add a new adapter." The agent reads the exact spec.
Run tests after every generation
npm test is your trust layer. AI code without tests is a liability. AI code with 298 tests is a foundation.
Example prompts
"Add a billing webhook handler that validates PayPal signatures and updates the license status in D1"
Claude Code will use the existing D1 setup, the Drizzle schema, and the license model — not invent a parallel one.
"Add a new RBAC role called 'editor' between admin and member with read-only access to the audit log"
Claude Code will use the existing rank-based RBAC system, add the role to the hierarchy, and update the capability matrix — the same pattern the starter uses for owner/admin/member.
"Write tests for the new role using the existing test patterns in tests/"
Claude Code will follow the existing test conventions (vitest, real DB, HTTP-level flows) — not invent a new testing approach.
Frequently asked questions
Does Claude Code work with SvelteKit?
Yes. Claude Code has strong SvelteKit support — it reads server-side code, form actions, load functions, and hooks. The VerdantStack starters add AGENTS.md to give it the specific patterns (Drizzle ORM, scrypt + hashed-session auth, RBAC middleware) so it doesn't reinvent them.
Will Claude Code rewrite the architecture?
Not if AGENTS.md has the right constraints. Claude Code treats AGENTS.md as a set of invariants. If you say "do not change the auth model", it won't. Without that file, it will. That's why we ship it.
How does this differ from just using Cursor or Copilot?
The starter kit is the same — it ships AGENTS.md and the API reference regardless of which AI tool you use. AGENTS.md is the cross-tool standard: Claude Code, Cursor, and Copilot all read it. The kit supports all three.
Can I use Claude Code to extend the starter with new features?
Yes — that's the primary use case. The starter gives Claude Code a known, tested foundation. You add features on top. The tests verify nothing broke. The audit log tracks what changed. The RBAC system controls who can do what.
What if I don't use AI coding tools?
The starter works the same way without AI tools. The AGENTS.md file is just documentation — readable by humans too. The test suite, the API reference, and the live demo all work independently. AI-agent readiness is an extra, not a requirement.
Try it
Every VerdantStack starter includes Claude Code support out of the box:
Related reading
Get in touch
Questions about the product, team licenses, or anything else? We'll respond within 48 hours.