solana-claude-md

Configuration files for AI coding assistants building Solana applications. Drop these files into your project to get production-ready code from Claude and other AI assistants.

Files Overview

File	Purpose	Best For
`CLAUDE.md`	Rules & constraints	Any Solana project (basic safety)
`SOLANA_EXPERT_AGENT.md`	Backend expertise	Programs, DeFi, security, infrastructure
`SOLANA_FRONTEND_AGENT.md`	Frontend expertise	UI/UX, design systems, accessibility

The Problem

AI coding assistants frequently make these mistakes when writing Solana code:

Using outdated libraries (solana-program 1.x, @solana/web3.js 1.x)
Missing critical account validation (owner checks, signer checks, PDA verification)
Using unsafe arithmetic without overflow protection
Deploying to mainnet without confirmation
Generating insecure patterns that pass compilation but fail audits
Creating inaccessible or poorly designed frontends

Installation

Option 1: npm (Recommended)

npx solana-claude-md

This installs all three configuration files to your current directory:

  ╔═══════════════════════════════════════════════╗
  ║   solana-claude-md                            ║
  ║   AI assistant config for Solana development  ║
  ╚═══════════════════════════════════════════════╝

Installing files...

  ✓  CLAUDE.md
  ✓  SOLANA_EXPERT_AGENT.md
  ✓  SOLANA_FRONTEND_AGENT.md

Installed 3 file(s)

CLI Options

# Install specific files only
npx solana-claude-md --claude      # Just CLAUDE.md
npx solana-claude-md --backend     # Just backend agent
npx solana-claude-md --frontend    # Just frontend agent

# Overwrite existing files
npx solana-claude-md --force

Option 2: curl (Manual)

# Basic rules
curl -O https://raw.githubusercontent.com/builderz-labs/solana-claude-md/main/CLAUDE.md

# Backend expert
curl -O https://raw.githubusercontent.com/builderz-labs/solana-claude-md/main/SOLANA_EXPERT_AGENT.md

# Frontend expert
curl -O https://raw.githubusercontent.com/builderz-labs/solana-claude-md/main/SOLANA_FRONTEND_AGENT.md

Option 3: Clone Repository

git clone https://github.com/builderz-labs/solana-claude-md.git
cp solana-claude-md/*.md /path/to/your/solana/project/

CLAUDE.md - Basic Rules

Drop this into any Solana project for immediate safety improvements. The AI assistant will automatically read and follow the rules.

What It Does

Uses modern libraries (Pinocchio 0.10, solana-program 3.0, @solana/kit)
Follows security best practices with explicit validation patterns
Chooses appropriate frameworks (Anchor vs Pinocchio vs Steel)
Tests properly with modern tools (Mollusk, LiteSVM, Trident)
Never deploys to mainnet without asking first

Sections Included

Section	Purpose
Modern Tooling	Current library versions and alternatives
Critical Rules	NEVER/ALWAYS rules that prevent mistakes
Framework Selection	When to use Anchor vs Pinocchio vs Steel
Program Patterns	Account validation with code examples
Testing	Mollusk, LiteSVM, Trident, Surfpool guidance
Client Development	Modern TypeScript patterns with @solana/kit
Deployment	Pre-flight checklist and mainnet safeguards
Security Checklist	Comprehensive validation requirements
Known Attacks	Type cosplay, CPI attacks, PDA exploits

SOLANA_EXPERT_AGENT.md - Backend Expert

Use this for comprehensive backend Solana development including smart contracts, DeFi protocols, and infrastructure.

What It Covers

Domain	Capabilities
Programs	Anchor 0.32, Pinocchio 0.10, Steel 4.0 with full code examples
DeFi	AMM curves (constant product, CLMM), vault accounting, oracle integration, lending protocols
NFTs	Metaplex Core, compressed NFTs (cNFTs), royalty enforcement
Testing	Mollusk unit tests, LiteSVM integration, Trident fuzzing
Infrastructure	Multi-RPC architecture, transaction landing strategies, Jito bundles
Security	Attack vectors, economic security, audit preparation
Network	Firedancer (1M TPS), Alpenglow (150ms finality), swQoS

Code Examples Included

AMM swap calculations with invariant checks
Vault share accounting (prevents inflation attacks)
Oracle integration with staleness checks (Pyth, Switchboard)
Lending protocol interest rate models
Compressed NFT minting
Transaction landing strategies

SOLANA_FRONTEND_AGENT.md - Frontend Expert

Use this for beautiful, accessible Solana dApp interfaces with modern design patterns.

What It Covers

Domain	Capabilities
Design System	8px grid, typography scale, semantic color tokens, dark mode
Components	shadcn/ui patterns, CVA variants, compound components
Animation	Framer Motion, micro-interactions (150-250ms), reduced motion support
Solana UI	Wallet connection, transaction flows, token display, NFT galleries
Accessibility	WCAG 2.2 AA, focus management, keyboard navigation, screen readers
Performance	React Server Components, lazy loading, image optimization
Forms	react-hook-form + zod validation, token inputs, address validation

2026 Design Trends

Liquid Glass: Translucency, blur effects, depth
Calm UI: Larger typography, generous whitespace, soft edges
Cognitive Inclusion: Design for diverse minds (ADHD, autism, dyslexia)
Warm Neutrals: Paper-like tones, reduced eye strain

Tech Stack

Technology	Version	Purpose
Next.js	15	App Router, RSC, Server Actions
React	19	Server Components, use() hook
TypeScript	5.x	Type safety
Tailwind CSS	4.0	@theme directive, CSS-first config
shadcn/ui	Latest	Radix primitives, CVA variants
Framer Motion	Latest	Physics-based animations

Components Included

WalletButton - Connection with dropdown menu
TransactionDialog - Full transaction flow with states
TokenBalance - Formatted display with abbreviations
AddressDisplay - Truncation, copy, explorer link
NFTGallery - Grid with lazy loading
TokenInput - Amount input with max/half buttons
TransferForm - Full form with validation

Requirements

Backend Development

# CLI Tools
Solana CLI: 3.1.0+ (via agave-install)
Rust: 1.79.0+
Anchor CLI: 0.32.0+ (if using Anchor)

# Cargo.toml (January 2026)
[dependencies]
anchor-lang = "0.32"      # If using Anchor
solana-program = "3.0"    # Or pinocchio for performance
pinocchio = "0.10"        # Zero-copy, minimal CUs
steel = "4.0"             # Native with better DX

[dev-dependencies]
mollusk-svm = "0.7"       # Fast unit testing
litesvm = "0.6"           # Integration testing
trident-fuzz = "0.2"      # Fuzz testing

Frontend Development

// package.json (January 2026)
{
  "dependencies": {
    "next": "^15.0.0",
    "react": "^19.0.0",
    "@solana/kit": "^2.0.0",
    "@solana/wallet-adapter-react": "^0.15.0",
    "tailwindcss": "^4.0.0",
    "framer-motion": "^11.0.0",
    "class-variance-authority": "^0.7.0",
    "react-hook-form": "^7.50.0",
    "zod": "^3.22.0"
  }
}

Customization

Set Your Stack

Uncomment and configure the stack section in CLAUDE.md:

# Framework: anchor | pinocchio | steel
# Client: typescript (@solana/kit) | rust | python
# Testing: mollusk | litesvm | trident
# Local: surfpool | solana-test-validator

Add Project-Specific Rules

## Project Rules

- All PDAs use the seed format: `[b"prefix", user.key().as_ref()]`
- Token amounts are stored as u64 with 9 decimals
- Admin operations require multisig (threshold: 2/3)

Testing the Configuration

Backend Rules

Ask the AI to implement a token transfer
Verify it:
- Uses modern libraries (not deprecated ones)
- Includes proper account validation
- Uses checked arithmetic
- Asks before deploying to mainnet

Frontend Rules

Ask the AI to create a wallet connect button
Verify it:
- Includes proper loading states
- Has accessibility attributes (aria-*, focus ring)
- Uses semantic color tokens
- Handles all states (disconnected, connecting, connected)

Claude Code Agents

These files can be used as Claude Code custom agents for specialized assistance:

# After adding to your project, the agents are automatically available
# in Claude Code when you reference the files

Agent	Trigger
Backend Expert	Reference `SOLANA_EXPERT_AGENT.md`
Frontend Expert	Reference `SOLANA_FRONTEND_AGENT.md`

Resources

Backend

Pinocchio Guide - Zero-copy Solana development
Steel Guide - Native Rust with better DX
Mollusk Testing - Fast unit testing
Solana Security Course - Security fundamentals
Surfpool - Local development with mainnet state

Frontend

shadcn/ui - Component library
Tailwind CSS 4.0 - CSS framework
Framer Motion - Animation library
WCAG 2.2 - Accessibility guidelines
Solana Wallet Adapter - Wallet integration

Contributing

Contributions welcome! Areas that could use improvement:

Additional security patterns
Framework-specific optimizations
More component examples
Python/Rust client patterns
Integration with security scanners

Please open an issue to discuss significant changes before submitting a PR.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.claude/agents		.claude/agents
bin		bin
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
SOLANA_EXPERT_AGENT.md		SOLANA_EXPERT_AGENT.md
SOLANA_FRONTEND_AGENT.md		SOLANA_FRONTEND_AGENT.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

solana-claude-md

Files Overview

The Problem

Installation

Option 1: npm (Recommended)

CLI Options

Option 2: curl (Manual)

Option 3: Clone Repository

CLAUDE.md - Basic Rules

What It Does

Sections Included

SOLANA_EXPERT_AGENT.md - Backend Expert

What It Covers

Code Examples Included

SOLANA_FRONTEND_AGENT.md - Frontend Expert

What It Covers

2026 Design Trends

Tech Stack

Components Included

Requirements

Backend Development

Frontend Development

Customization

Set Your Stack

Add Project-Specific Rules

Testing the Configuration

Backend Rules

Frontend Rules

Claude Code Agents

Resources

Backend

Frontend

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 1

Languages

Packages