Claude Code for Flow Development

Overview

Claude Code (CC) provides an AI-powered coding assistant specifically designed for iterative, systematic development, which transforms the development experience. Unlike general-purpose AI tools, CC excels at breaking down tasks into manageable, incremental steps while maintaining context across your entire development lifecycle.

What makes CC exceptionally powerful is it can maintain unlimited context windows, which allows it to understand entire codebases without the compression limitations that plague other AI coding tools. This comprehensive understanding allows CC to deploy multiple subagent instances that work in parallel on complex tasks, iterate continuously until optimal solutions are achieved, and maintain persistent memory of your project's architecture and coding standards across all development sessions.

Learning Objectives

After you complete this guide, you'll be able to:

• Set up and configure CC for optimal Flow blockchain development workflows.
• Implement the four-stage development methodology (Idea → Visualization → Planning → Build) for Cadence projects.
• Configure persistent project context with CLAUDE.md files with Flow-specific instructions and MCP tools.
• Apply iterative development practices with git-based checkpoint systems for safe blockchain development.
• Use advanced CC features including subagents, auto-verification, and specialized debugging workflows.
• Integrate CC with Flow CLI, FCL, and other Flow development tools for comprehensive project management.
• Create and manage team-wide development standards through shared CLAUDE.md configurations.

Prerequisites

Before you proceed with this guide, you should have:

Technical Requirements

• Claude Code Subscription: $200/month plan recommended for comprehensive Flow development features.
• Flow CLI: Installed and configured for emulator, testnet, and mainnet interactions.
• Git: Version control system for checkpoint-based development workflow.
• Node.js: For CC, FCL integration, and frontend development components.

CC Setup and Configuration

What is CC?

CC is an AI-powered coding assitant that integrated directly into your terminal. This allows you to use it in any integrated development environment (IDE) or simply from your terminal. The power of CC comes from its ability to explain complex and large codebases, manage Git workflows, and iterate for long periods of time to accomplish a task.

Most IDEs like Cursor rely on their ability to compress the context window that is fed to agents so that their business model justifies charging $20 while using expensive LLM models. This naturally decreases the ability of the agents to have a comprehensive understanding of the working codebase when managing with large or complex codebases.

This is why CC can be so powerful, because it can include entire codebases in its context, deploy other instances of CC to work on multiple actions in parallel, and iterate on its results in order to achieve better results.

Installation and Subscription

CC requires a subscription to access its full development capabilities. There are three subscription levels: Pro, Max 5x, and Max 20x.

The Pro plan is very limited, so expect it to only be sufficient for testing and experimentation.

The $200/month Max 20x plan is recommended for developers with a lot of projects or if you need to build something quickly where time is crucial. This plan grants you access to:

• Unlimited context windows for complex smart contract projects.
• Advanced subagent capabilities for parallel development tasks.
• Persistent memory across development sessions.
• Integration with MCP (Model Context Protocol) servers.
• Team collaboration features through shared configurations.

You can also use the API pricing, but this isn't recommended since any meaningful implementation of CC most likely requires more than $100 in API credits.

Initial Configuration

To install CC, run the following command:

_10

npm install -g @anthropic-ai/claude-code

After the installation process completes, navigate to your project and start CC:

_10

cd your-awesome-project

_10

claude

This automatically installs the extension. You can run the /ide command in the CC terminal to make sure your IDE is connected to CC. With the extension installed, you can click on the orange Anthropic logo on the upper right hand of the screen in order to launch CC in a separate window.

CLAUDE.md Files

CLAUDE.md files are configuration files that contain project-specific instructions and context for CC. They allow you to define development standards, frequently used commands, and project architecture that the AI remembers across all coding sessions. They are similar to Cursor Rules, but they differ in that CLAUDE.md only specifies the configuration of CC.

If you are now sure of what type of information to place in your CLAUDE.md file, create your primary CLAUDE.md file in the project root. Use the /init command in CC to generate the initial structure, then customize for Flow development:

Create your Flow project with the standard directory structure:

_15

flow-project/

_15

├── .claude/

_15

│ └── CLAUDE.md # Project-wide AI instructions

_15

├── cadence/

_15

│ ├── .claude/

_15

│ │ └── CLAUDE.md # Cadence-specific instructions

_15

│ ├── contracts/

_15

│ ├── transactions/

_15

│ └── scripts/

_15

├── frontend/

_15

│ ├── .claude/

_15

│ │ └── CLAUDE.md # Frontend-specific instructions

_15

│ └── src/

_15

├── flow.json # Flow project configuration

_15

└── package.json

3. Root CLAUDE.md Configuration

Placing CLAUDE.md in the root file sets the instructions you want CC to do frequently, such as:

• Bash commands you want to run frequently.
• Files it should really know about when making changes or big architectural decisions.
• MCP servers.

This file is great for sharing across your team so you set it once and everyone has the same extended functionality.

Team Configuration Setup:

_38

_38

# Flow Project AI Assistant Configuration

_38

_38

## Project Overview

_38

_38

This is a Flow blockchain application with Cadence smart contracts and FCL frontend integration.

_38

_38

## Team-wide Development Standards

_38

_38

- MCP servers standardized across development environments.

_38

- Git workflow and commit message standards enforced.

_38

- Follow official Flow documentation patterns.

_38

- Use incremental, checkpoint-based development.

_38

- Test on emulator before testnet deployment.

_38

- Implement proper resource handling with @ and & syntax

_38

- Follow MetadataViews standards for NFT projects.

_38

_38

## Frequently Used Commands

_38

_38

- `flow emulator start` - Start local development environment.

_38

- `flow project deploy --network emulator` - Deploy contracts locally.

_38

- `flow transactions send ./cadence/transactions/example.cdc --network emulator` - Execute transactions locally.

_38

- `npm run dev` - Start frontend development server.

_38

_38

## Key Files to Reference

_38

_38

- `flow.json` - Project configuration and contract deployments.

_38

- `cadence/contracts/` - Smart contract implementations.

_38

- `frontend/src/config.js` - FCL configuration and contract addresses.

_38

_38

## MCP Servers

_38

_38

- Use flow-mcp for reading blockchain data, managing accounts, checking balances, and interacting with native contracts.

_38

- Use flow-defi-mcp fro checking token prices, swapping tokens on decentralized exchanges, and interacting with ERC20 tokens.

_38

_38

## Architecture Notes

_38

_38

[Document your specific project architecture, contract relationships, and deployment strategies]

3. Nested CLAUDE.md Files

You can maintain a more granular control of the capabilities of CC when working with different ares of your repo by creating specialized instructions for different project areas. To do this, place a nested CLAUDE.md file in subdirectories in your repo(cadence, frontend, backend, and so on). CC will automatically read these files when working on these subdirectories. Here is an example:

cadence/.claude/CLAUDE.md:

_25

# Cadence Development Instructions

_25

_25

## Syntax Requirements

_25

_25

- Always use proper resource syntax: @{NonFungibleToken.NFT}

_25

- Implement required interfaces: NonFungibleToken, MetadataViews.

_25

- Use view functions for read-only operations.

_25

- Follow auth capability patterns for transactions.

_25

_25

## Testing Protocol

_25

_25

- Write unit tests for all contract functions.

_25

- Test resource creation and destruction.

_25

- Verify proper event emission.

_25

- Validate access controls and permissions.

_25

- Test for breaking changes and edge cases.

_25

_25

## Standard Patterns

_25

_25

Reference the Flow documentation for:

_25

_25

- Contract deployment and initialization.

_25

- Resource collection patterns.

_25

- Proper error handling and panics.

_25

- Gas optimization techniques.

frontend/.claude/CLAUDE.md:

_14

# Frontend FCL Integration Instructions

_14

_14

## Configuration Management

_14

_14

- Keep contract addresses in environment variables.

_14

- Use proper network switching logic.

_14

- Implement user authentication flows.

_14

- Handle transaction status updates.

_14

_14

## Best Practices

_14

_14

- Show loading states for blockchain interactions.

_14

- Provide clear error messages for failed transactions.

_14

- Cache contract data when appropriate.

Local Claude.md

You can also create a CLAUDE.local.md file that is used just for you and not shared with your team.

Workflow Strategies

CC excels when following a structured development approach. We recommend you implement this four-stage methodology:

Stage 1: Idea Development

Objective: Bounce ideas with CC to have a better understanding of what you can build and why it would work.

Process:

1. Click Shift + Tab to cycle through the different response forms that CC offers until you reach the Plan Mode.

2. Describe your Flow project concept to CC.
3. Ask for requirement analysis and technical feasibility assessment.

Example Conversation:

_10

User: "I want to create a collectible card game on Flow where players can battle and evolve their cards"

_10

_10

CC Response: [Analyzes requirements, suggests NFT architecture, identifies game mechanics, proposes contract structure]

Outputs:

• Detailed project requirements document.
• Technical architecture overview.
• Flow-specific implementation considerations.
• Resource and timeline estimates.

Stage 2: Visualization

Objective: Create visual representations and demos to validate project concepts before development. You can use CC during this process, but it is best to combine LLM models like Gemini 2.5 in order to create the visual representations.

Tools and Techniques:

• Mermaid Diagrams: Generate contract relationship diagrams, user flow charts, and system architecture visuals.
• UI Mockups: Create interface mockups for frontend applications.
• Contract Schemas: Visualize data structures and resource relationships.
• Transaction Flow Maps: Diagram user interactions and blockchain state changes.

Example Workflow:

_10

User: "Create a diagram showing how card evolution works in my game"

_10

_10

[CC generates Mermaid diagram showing contract interactions, resource transformations, and event emissions]

Claude Code Commands:

• Use image upload to share visual concepts.
• Request Mermaid diagrams for complex systems.
• Ask for UI mockups based on Flow wallet integration patterns.

Stage 3: Planning with Claude Code

Objective: Break down the project into manageable, incremental development tasks using CC's planning capabilities.

Planning Process:

1. Enable Planning Mode: Explicitly tell CC you're in planning phase or cycle through the different modes (with Shift + Tab) until you reach Plan Mode
2. Confirm Knowledge Comprehension: Ask CC to read important files first and then confirm the knowledge with you. Immediately ask it questions about the codebase to verify its knowledge
3. Plan Generation: Tell CC to generate an action plan that is incremental and has specific goals and checkpoints (this file can be called T0-DO.md and placed in a /tasks folder that contains relevant information about the completion of specific tasks or steps).
4. Task Breakdown: Request comprehensive task decomposition for incremental changes.
5. Dependency Mapping: Identify task dependencies and critical path.
6. Checkpoint Strategy: Define git commit points and testing milestones.

Example Planning Session:

_18

User: "Set up a roadmap and plan of the to-do's that need to be completed for my card game NFT contracts"

_18

_18

CC Response:

_18

Task 1: Set up basic NFT contract structure

_18

- Implement NonFungibleToken interface

_18

- Add MetadataViews compatibility

_18

- Create basic card resource

_18

- Write deployment transaction

_18

- Checkpoint: Basic NFT functionality

_18

_18

Task 2: Add game mechanics

_18

- Implement battle system

_18

- Add evolution functionality

_18

- Create game state management

_18

- Write game transaction scripts

_18

- Checkpoint: Core game mechanics

_18

_18

[Continues with detailed breakdown]

Planning Outputs:

• Generate a detailed to-do list that is thoroughly divided between goals, objectives, checkpoints and tasks that need to be achieved in an incremental manner.
• Dependency graph showing task relationships.
• Testing strategy for each development phase.
• Deployment sequence and validation protocols.

A downside of using CC is that it doesn't have a checkpoint control like the agent chat does in Cursor. So making frequent git commits and working on separate branches can help you mitigate this. Never attempt to give CC a big task as it most likely doesn't have enough knowledge about the task at hand to complete it successfully.

Stage 4: Build Execution

Objective: Implement planned tasks systematically using CC's development capabilities.

Build Process:

1. Task Assignment: Work on one incremental task at a time.
2. Implementation: Use CC to generate code, debug issues, and optimize solutions.
3. Reporting: After completing a task, CC generates a report of what it did and why it did it in a .md file in the /tasks folder so that you can have a better understanding of the changes made.
4. Validation: Test each component thoroughly before you proceed.
5. Documentation: Generate inline documentation and update project docs.
6. Checkpoint: Commit working code with descriptive messages.
7. Updating: Ask CC to update the TO-DO.md with the completed steps and changes after the commit is approved.

Development Workflow:

_11

User: "Implement Task 1: Basic NFT contract structure"

_11

_11

[CC generates contract code, deployment scripts, and tests]

_11

_11

User: "Test this implementation"

_11

_11

[CC provides testing commands and validation scripts]

_11

_11

User: "Commit this checkpoint"

_11

_11

[CC suggests commit message and validates completion]

Advanced Claude Code Features

Subagent Utilization

For complex Flow projects, leverage CC's subagent capabilities to handle parallel development tasks:

When to Use Subagents:

• Developing multiple contracts simultaneously.
• Frontend and backend development in parallel.
• Testing different implementation approaches.
• Documentation generation while coding.
• Dealing with a big task so that CC can deploy subagents to break down the task into smaller components that are running in parallel.

Example Subagent Usage:

_10

User: "Create subagents to develop the NFT contract and the marketplace contract in parallel"

_10

_10

[CC spawns separate conversation threads for each contract, maintaining coordination between them]

Auto-Verification and Iteration

Configure CC to automatically verify its work and iterate for improvements:

Verification Patterns:

• Compilation Checks: Automatically test Cadence syntax after code generation.
• Test Execution: Run unit tests and integration tests after implementation.
• Deployment Validation: Verify contract deployment on emulator before suggesting testnet deployment.

Memory and Context Management

Using the # Memory Mode: Press # to enter memory mode and specify important information for CC to remember:

_10

# Remember that this project uses a modular NFT architecture with separate traits contracts.

_10

# Remember that we need to use a DS Proxy system for upgrading contracts.

Context Optimization:

• Use Ctrl+R for verbose output when debugging complex issues.
• Compact conversations at natural breakpoints (around 20% context usage).
• Constantly refactor CLAUDE.md to take into account changes made throughout the development process.
• Maintain focused conversations for specific development tasks.

Development Workflows and Best Practices

Give CC some sort of tool it can use for feedback (MCP or tool) to check its work and it will iterate by itself to get better results. CC has the ability to iterate for hours if needed, but it needs to be able to analyze its work. These alternative workflows can be very useful as well, depending on your ability to close the feedback loop so that CC can analyze and comprehend the results of its code generation:

Test-Driven Development with Claude Code

Workflow: Write Tests → Commit → Code → Iterate → Commit

_10

User: "Write tests for card evolution functionality first"

_10

_10

[CC generates comprehensive test suite]

_10

_10

User: "Now implement the evolution logic to pass these tests"

_10

_10

[CC implements feature with test-driven approach]

Screenshot-Driven Development

Workflow: Write Code → Screenshot Result → Iterate

Particularly useful for frontend development:

_10

User: "Implement this card display component"

_10

_10

[CC generates React component]

_10

_10

User: [Uploads screenshot of result]

_10

_10

CC: "I see the card layout needs improvement. Let me adjust the CSS..."

Checkpoint-Based Development

Best Practices:

• Commit after each completed task
• Use descriptive commit messages that CC generates.
• Create branches for experimental features.
• Tag stable releases for easy rollback.

Example Checkpoint Strategy:

_10

git commit -m "feat: implement basic NFT contract with MetadataViews

_10

_10

- Add NonFungibleToken interface implementation

_10

- Include required MetadataViews for marketplace compatibility

_10

- Create basic card resource with metadata

_10

- Add deployment transaction and initialization script

_10

- All tests passing on emulator

_10

_10

Checkpoint: Basic NFT functionality complete"

Error Resolution and Debugging

Systematic Debugging Approach:

1. Error Analysis: Provide CC with complete error messages and context.
2. Root Cause Investigation: Let CC analyze potential causes.
3. Solution Implementation: Apply suggested fixes incrementally.
4. Verification: Test fixes thoroughly before proceeding.
5. Documentation: Update project documentation with lessons learned.

Example Debugging Session:

_10

User: "Getting authorization error in my transaction"

_10

_10

CC: "Let me analyze the auth capability requirements. I see the issue is with the granular auth pattern. Here's the fix..."

_10

_10

[Provides corrected transaction with proper auth syntax]

Multi-Network Deployment

Deployment Workflow with Claude Code:

1. Emulator Testing: Comprehensive local testing and validation.
2. Configuration Update: Update flow.json and FCL config for testnet.
3. Testnet Deployment: Deploy and validate on testnet.
4. Frontend Integration: Update frontend configuration and test user flows.
5. Mainnet Preparation: Final validation and deployment to mainnet.

MCP Server Sharing

You can set up MCPs for CC to use as tools. These can also be set up in the CLAUDE.md file so that every team member consistently uses the same MCPs. Share the /Claude/mcp.json files so that the team can use the same MCP servers.

Team MCP Configuration:

To grant Claude Code access to use an MCP server, run the following commands:

_10

# Adding a MCP server

_10

claude mcp add <name> <command> [args...]

_10

_10

# Adding a local server

_10

claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2

You can also try these MCPs for Flow development:

_10

# Shared MCP servers for team consistency

_10

claude mcp add flow_mcp

_10

claude mcp add flow-defi-mcp

Version Control for AI Configuration

Best Practices:

• Include CLAUDE.md files in version control.
• Document MCP server configurations in README.
• Share CLAUDE.local.md patterns (without committing personal configs).
• Maintain team coding standards through shared AI instructions.

Key Bindings and Shortcuts

Essential Claude Code Shortcuts

Shortcut	Function	Flow Development Usage
#	Memory mode	Store project architecture decisions
Shift+Tab	Auto-accept edits	Quickly accept generated Cadence code
!	Bash mode	Execute Flow CLI commands directly
@	Add file/folder	Reference contracts, transactions, configs
Esc	Cancel operation	Stop incorrect generation/execution
Ctrl+R	Verbose output	Detailed debugging for complex issues

Flow-Specific Usage Patterns

Memory Mode Examples:

_10

# This project follows the composite NFT pattern with separate trait contracts.

_10

# Gas optimization is critical - avoid loops in public functions.

_10

# All contracts must support MetadataViews for marketplace compatibility.

File Reference Patterns:

_10

@flow.json - Project configuration

_10

@cadence/contracts/MyNFT.cdc - Main NFT contract

Troubleshooting and Optimization

Common Issues and Solutions

Context Window Management:

• Compact conversations at natural breakpoints or manually at around 20% of context usage remaining.
• Use focused sub-conversations for specific tasks.
• Reference key files rather than copying entire contents.

Performance Optimization:

• Use the $200/month plan for complex Flow projects.
• Turn on auto-compact to prevent context overflow.
• Break large tasks into smaller, focused conversations.
• Hit Esc often if you see the agent is going on the wrong path and ask it to undo its recent action.

Integration Problems:

• Verify MCP server configurations.
• Check Flow CLI integration and permissions.
• Validate CLAUDE.md file syntax and structure.

Best Practices for Flow Development

Project Management:

• Maintain clear separation between contracts, transactions, and frontend code.
• Use nested CLAUDE.md files for different development areas.
• Keep project documentation synchronized with implementation.

Code Quality:

• Always compile Cadence code before deployment.
• Use CC for security review suggestions.
• Implement comprehensive testing at each development stage.

Deployment Management:

• Test thoroughly on emulator before testnet deployment.
• Validate FCL configuration changes across networks.
• Use systematic deployment checklists that CC generates.

Conclusion

In this guide, you explored how to leverage CC for efficient Flow blockchain and Cadence development. You learned to implement a systematic four-stage development methodology that transforms ideas into production-ready applications through AI-assisted visualization, planning, and execution.

You discovered how to configure persistent project context through CLAUDE.md files, allowing your AI assistant to maintain comprehensive understanding of Flow-specific patterns, project architecture, and team standards across all development sessions. The integration of specialized tools like Flow CLI, FCL configuration management, and MCP servers creates a comprehensive development environment optimized for blockchain application building.

The systematic approaches covered - from test-driven development and checkpoint-based workflows to subagent utilization and auto-verification - provide a foundation for building complex Flow applications with confidence and efficiency. The emphasis on incremental development, comprehensive testing, and systematic deployment ensures your projects meet the reliability requirements essential for blockchain applications.

Now that you have completed this guide, you should be able to:

• Set up and configure CC for optimal Flow blockchain development workflows with persistent context and specialized tooling.
• Implement the four-stage development methodology (Idea → Visualization → Planning → Build) for systematic Cadence project development.
• Apply advanced CC features including subagents, auto-verification, and team collaboration patterns for complex Flow applications.
• Integrate CC seamlessly with Flow CLI, FCL, and other Flow development tools for comprehensive project management across emulator, testnet, and mainnet environments.

The combination of AI-powered development assistance with Flow's comprehensive toolchain creates an unprecedented opportunity for building sophisticated blockchain applications efficiently and reliably. As you continue developing on Flow, these systematic approaches will help you maintain high code quality while accelerating your development velocity.