This guide documents the complete Claude Code setup for this Next.js 15 project, including current configuration, specialized agents, MCP integrations, and optimization recommendations.
Our project has a sophisticated Claude Code setup with the following components:
CLAUDE.md).claude/settings.json){
"permissions": {
"allow": [
"Bash(pnpm add:*)",
"Bash(pnpm list:*)",
"Bash(mkdir:*)",
"Bash(pnpm prisma generate:*)"
],
"deny": [],
"ask": []
}
}.claude/agents/)We have 9 specialized agents configured:
| Agent | Model | Purpose | Status |
|---|---|---|---|
nextjs-expert | opus | Next.js optimization & architecture | ✅ Active |
shadcn-ui-specialist | opus | UI/UX design with shadcn/ui | ✅ Active |
react-code-reviewer | default | Code quality & best practices | ✅ Active |
typescript-pro | default | TypeScript expertise | ✅ Active |
architect | opus | System architecture guidance with mirror-pattern | ✅ Active |
bug-detective | default | Debugging & troubleshooting | ✅ Active |
unit-test-writer | default | Test creation & coverage | ✅ Active |
typography-refactor | default | Typography system compliance | ✅ Active |
nextjs-devops-architect | default | DevOps & deployment | ✅ Active |
.mcp.json)We have 9 MCP servers configured:
Development & Monitoring:
vercel - Deployment management & monitoringsentry - Error tracking & debuggingpostgres-dev - Database queries & managementDesign & Content:
figma - Design system integrationnotion - Documentation & knowledge baseairtable - Content managementProject Management:
linear - Issue tracking & project managementclickup - Task management & trackingstripe - Payment processing (business context)Current State: Basic permissions with only a few allowed commands Recommended: Implement comprehensive security model
{
"permissions": {
"allow": [
"Bash(pnpm add:*)",
"Bash(pnpm list:*)",
"Bash(mkdir:*)",
"Bash(pnpm prisma generate:*)",
"Bash(pnpm run lint)",
"Bash(pnpm run build)",
"Bash(pnpm run test:*)",
"Bash(git status)",
"Bash(git diff)",
"Bash(git add:*)",
"Bash(git commit:*)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Write(./.env*)",
"Bash(rm:*)",
"Bash(sudo:*)",
"WebFetch(*malicious*)",
"Bash(curl:*external-api*)"
],
"ask": [
"Bash(git push:*)",
"Bash(pnpm publish:*)",
"Write(./package.json)",
"Write(./prisma/schema.prisma)"
]
}
}Current State: No hooks configured Recommended: Add automated code quality hooks
Create .claude/hooks/:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "if echo '$file_path' | grep -q '\\.tsx\\?$'; then pnpm run lint:fix $file_path; fi"
}
]
}
],
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo 'Ensuring TypeScript compliance before file creation'"
}
]
}
]
}
}Current State: Default model usage Recommended: Strategic model allocation
{
"model": "sonnet",
"env": {
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-1-20250805",
"CLAUDE_CODE_SUBAGENT_MODEL": "opus"
}
}Current State: Basic environment setup Recommended: Secure environment management
{
"env": {
"NODE_ENV": "development",
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"DISABLE_TELEMETRY": "0",
"MAX_MCP_OUTPUT_TOKENS": "50000"
},
"permissions": {
"additionalDirectories": ["../docs/", "./public/"],
"defaultMode": "default"
}
}Create monitoring script for MCP servers:
#!/bin/bash
# .claude/scripts/mcp-health.sh
echo "Checking MCP server status..."
# Check HTTP servers
curl -s "https://mcp.vercel.com/health" || echo "❌ Vercel MCP down"
curl -s "https://mcp.sentry.dev/health" || echo "❌ Sentry MCP down"
curl -s "https://mcp.notion.com/health" || echo "❌ Notion MCP down"
# Check local Figma server
curl -s "http://127.0.0.1:3845/health" || echo "⚠️ Figma MCP not running"
echo "✅ MCP health check complete"Current: All agents use default/opus models Recommended: Optimize for speed vs. quality balance
# Update agent configurations
nextjs-expert: opus (complex architecture decisions)
shadcn-ui-specialist: sonnet (UI implementation)
react-code-reviewer: sonnet (code review)
typescript-pro: sonnet (type fixes)
bug-detective: opus (complex debugging)
unit-test-writer: sonnet (test generation)Use Specialized Agents Proactively:
# For UI work
> Use the shadcn-ui-specialist to create a new dashboard component
# For architecture decisions
> Have the nextjs-expert optimize our API route structure
# For debugging
> Ask the bug-detective to investigate this React hydration errorChain Agents for Complex Tasks:
# Multi-step development
> First use architect to plan the feature, then nextjs-expert to implement, then react-code-reviewer to validateVercel Integration:
# Deployment monitoring
> Check our latest deployment status on Vercel and analyze any errors
# Performance optimization
> Use Vercel analytics to identify slow pages and suggest optimizationsDevelopment Workflow:
# Issue → Design → Code → Deploy
> Check Linear for priority issues, get designs from Figma, implement with Next.js patterns, deploy via VercelProject-Specific Instructions:
Agent-Specific Memory:
# Add to CLAUDE.md
## Component Patterns
- Use Server Components by default
- Add "use client" only for interactivity
- Follow atomic design: atom → molecule → organismEnvironment Protection:
{
"permissions": {
"deny": [
"Read(./.env*)",
"Read(./secrets/**)",
"Read(./.aws/**)",
"Write(./.env*)",
"Bash(curl:*api-key*)",
"WebFetch(*admin*)"
]
}
}Safe Development Commands:
{
"permissions": {
"allow": [
"Bash(pnpm run *)",
"Bash(git diff)",
"Bash(git status)",
"Bash(git log:*)"
],
"ask": [
"Bash(git push:*)",
"Bash(git reset:*)"
]
}
}Create .claude/statusline.sh:
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
BRANCH=$(git branch --show-current 2>/dev/null || echo "no-git")
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
echo "[$MODEL] 🌿 $BRANCH | 💰 \$$(printf '%.4f' $COST)"For learning mode:
/output-style learningFor explanatory mode:
/output-style explanatoryCreate .github/workflows/claude-code.yml:
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
claude-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "/review"Monitor Claude Code effectiveness:
Based on the YouTube video insights:
From the referenced YouTube video, key optimizations:
MCP Connection Failures:
# Reset MCP configuration
claude mcp reset-project-choices
# Test individual servers
curl -s https://mcp.vercel.com/Agent Not Responding:
# Check agent configuration
/agents
# Verify model availability
/statusPermission Denied:
# Review current permissions
/config
# Temporary bypass (use carefully)
/permission-mode bypassThis comprehensive setup positions your project for optimal Claude Code usage with security, performance, and team collaboration in mind.
On This Page
Claude Code Configuration & Setup Guide🔍 Current Setup AnalysisCore Configuration Files1. Project Memory (CLAUDE.md)2. Settings Configuration (.claude/settings.json)3. Specialized Agents (.claude/agents/)4. MCP Server Integrations (.mcp.json)🎯 Areas for Improvement1. Security & Permissions Enhancement2. Hooks Implementation3. Model Configuration Optimization4. Enhanced Environment Security🚀 Performance Optimizations1. MCP Server Health Monitoring2. Agent Optimization💡 Expert Tips & Best Practices1. Workflow Optimization2. MCP Integration Patterns3. Memory Management4. Security Best Practices🔧 Advanced Configuration1. Custom Status Line2. Output Style Customization3. GitHub Actions Integration📊 Monitoring & Metrics1. Usage Tracking2. Cost Optimization🎬 Video Integration Notes🔮 Future Enhancements1. Planned Additions2. Advanced Features3. Team Collaboration🆘 TroubleshootingCommon Issues