Customization

Introduction

The Claude Workflow system is designed to be highly customizable. Every component—agents, commands, sessions, tools—can be adapted, simplified, or replaced to match your team's needs and preferences.

Core Philosophy: "Use what helps, skip what doesn't."

This guide shows you how to customize the workflow for your specific situation.

Why Customize?

Team Size

Solo Developer:

• Skip PM agent (write requirements manually)
• Skip QA agent (manual testing)
• Skip code review agent (self-review)
• Simplified 2-phase workflow

Small Team (2-5 people):

• Keep PM and Architect
• Combine frontend/backend into single developer role
• Keep QA
• Optional code review

Large Team (5+ people):

• Full agent suite
• Add specialized agents (mobile, DevOps, security)
• Detailed handoffs
• Comprehensive documentation

Project Complexity

Simple Projects:

• Minimal agents
• Simplified workflow
• Less documentation
• Faster iterations

Complex Projects:

• Full agent suite
• Detailed planning
• Comprehensive testing
• Complete documentation

Development Style

Waterfall:

• Sequential phases
• Complete planning upfront
• Formal handoffs
• Detailed documentation

Agile:

• Iterative phases
• Just-in-time planning
• Flexible handoffs
• Living documentation

Ad-Hoc:

• Use agents as needed
• No fixed workflow
• Minimal structure
• Lightweight tracking

---

Customization Areas

1. Agents

Simplify Agent Set:

# Minimal setup for solo developer
.claude/agents/
├── planner.md          # Combined PM + Architect
└── developer.md        # Combined FE + BE

Expand Agent Set:

# Enterprise setup
.claude/agents/
├── product-manager.md
├── architecture-supervisor.md
├── frontend-developer.md
├── backend-developer.md
├── mobile-developer.md        # NEW
├── devops-engineer.md         # NEW
├── security-specialist.md      # NEW
├── qa-tester.md
├── code-reviewer.md
└── documentation-writer.md

Modify Existing Agents:

Edit agent file to change behavior:

<!-- .claude/agents/frontend-developer.md -->

## Custom Team Patterns

Your team-specific requirements:
- Use CSS Modules instead of Tailwind
- Follow company component library
- Create visual regression tests
- Document in Storybook

## Custom Tools

tools: Bash, Read, Write, Edit, Storybook, Percy

Create Custom Agent:

# Create new specialized agent
touch .claude/agents/mobile-developer.md

---
name: mobile-developer
description: Develops mobile features using React Native
model: sonnet
color: pink
tools: Bash, Read, Write, Edit
---

You are an expert mobile developer specializing in React Native...

## Core Responsibilities

- Implement React Native components
- Handle platform-specific code (iOS/Android)
- Optimize for mobile performance
- Ensure touch interactions work properly
- Test on physical devices

## Mobile-Specific Patterns

- Use Expo for rapid development
- Implement offline-first architecture
- Optimize bundle size
- Handle push notifications

## Testing Requirements

- Test on iOS and Android simulators
- Verify on physical devices
- Check different screen sizes
- Validate performance (60fps)

---

2. Workflow Phases

Simplify to 2 Phases:

1. Planning → 2. Implementation

Skip QA and code review for internal tools or prototypes.

Expand to 6 Phases:

1. Requirements →
2. Architecture →
3. Development →
4. QA Testing →
5. Security Review →  # NEW
6. Code Review

Add security review for compliance-heavy projects.

Custom Phase Order:

1. Spike/Prototype →  # NEW - Explore solution
2. Planning →
3. Implementation →
4. Review

Add prototyping phase for uncertain technical approaches.

Parallel Phases:

        ┌─> Frontend Dev ─┐
Planning ┤                ├─> QA → Review
        └─> Backend Dev ─┘

Frontend and backend work in parallel.

---

3. Session Structure

Minimal Session (2 files):

.claude/sessions/feature-name/
├── plan.md         # Combined business + technical
└── progress.md     # Simple checklist

Skip separate business requirements and context files for simple projects.

Extended Session (6 files):

.claude/sessions/feature-name/
├── requirements.md     # Business requirements
├── plan.md            # Technical plan
├── progress.md        # Progress tracking
├── context.md         # Agent coordination
├── testing.md         # Test results & bugs  # NEW
└── review.md          # Code review details  # NEW

Add dedicated testing and review files for detailed tracking.

Custom Session Files:

.claude/sessions/feature-name/
├── clickup_task.md
├── plan.md
├── progress.md
├── context.md
├── dependencies.md    # NEW - External dependencies
├── metrics.md         # NEW - Performance metrics
└── deployment.md      # NEW - Deployment steps

Add files for specific team needs.

---

4. Project Management Tools

Use GitHub Issues:

Setup:

## GitHub Configuration
**Repository:** owner/repo
**Token:** ghp_xxxxx
**Labels:** feature, bug, enhancement

Agent Modifications:

<!-- PM agent creates GitHub issue -->
await github.issues.create({
  title: featureName,
  body: description,
  labels: ['feature'],
  assignees: [username]
})

Use Linear:

## Linear Configuration
**Workspace:** company-name
**API Key:** lin_api_xxxxx
**Team:** Engineering

Use Jira:

## Jira Configuration
**Instance:** company.atlassian.net
**Project:** PROJ
**API Token:** xxxxx

Use Nothing:

## No External Tool

Track everything in session files only.

---

5. Commands

Create Team-Specific Commands:

Example: /quick-fix Command

---
description: Quick bug fix workflow (no PM or architect)
---

# Quick Fix

For simple bug fixes that don't need planning.

**Bug Description:**
{{{ input }}}

## Phase 1: Create Minimal Session

```typescript
const sessionName = bugDescription.toLowerCase().replace(/\s+/g, '-')
mkdir `.claude/sessions/${sessionName}`

// Create only progress file
createFile(`${sessionName}/progress.md`, `
  - [ ] Reproduce bug
  - [ ] Identify root cause
  - [ ] Implement fix
  - [ ] Test fix
  - [ ] Update relevant docs
`)

Phase 2: Implementation

Launch appropriate developer agent to:

1. Reproduce and fix bug
2. Mark progress
3. Validate fix

Phase 3: Quick QA

Launch QA agent to verify fix only (no full test suite).

Output

• Bug fixed
• Progress marked
• Tested

No ClickUp task, no extensive planning.

**Usage:**
```bash
/quick-fix Profile image not uploading

Example: /deploy Command

---
description: Deploy feature to staging/production
---

# Deploy Feature

**Session Name:**
{{{ input }}}

## Phase 1: Pre-Deployment Checks

- Verify all tests pass
- Check code review approved
- Validate build succeeds
- Run security scan

## Phase 2: Deployment

Launch devops-engineer agent to:
- Deploy to staging
- Run smoke tests
- Monitor for errors
- Deploy to production if staging passes

## Phase 3: Post-Deployment

- Update ClickUp to "deployed"
- Notify stakeholders
- Monitor metrics

---

6. Testing Approach

Manual Testing Only:

<!-- qa-tester.md -->

## Testing Approach

All testing is manual - no automated tests required.

### Process
1. Test functionality manually
2. Document results in context file
3. Create bug reports if needed

Automated Testing Priority:

<!-- qa-tester.md -->

## Testing Approach

Automated tests required before manual testing.

### Process
1. Verify unit tests pass
2. Verify integration tests pass
3. Verify E2E tests pass
4. Manual exploratory testing
5. Document all results

Visual Regression Testing:

<!-- qa-tester.md -->

## Testing Approach

Include visual regression tests for all UI changes.

### Tools
- Percy for screenshots
- Chromatic for Storybook
- Manual visual review

### Process
1. Run automated tests
2. Run visual regression tests
3. Review visual diffs
4. Manual testing

---

7. Code Review Process

Self-Review Only:

<!-- Skip code-reviewer agent -->

Developers self-review using checklist:
- [ ] Tests pass
- [ ] No linting errors
- [ ] Performance acceptable
- [ ] Security considerations addressed
- [ ] Documentation updated

Peer Review:

<!-- Human developer reviews -->

1. Developer creates PR
2. Team member reviews manually
3. Approves or requests changes

AI + Human Review:

<!-- code-reviewer agent + human -->

1. code-reviewer agent posts initial review
2. Human developer reviews AI feedback
3. Human makes final decision

Automated Only:

<!-- Linters + tests only -->

1. Linters must pass
2. Tests must pass
3. Auto-merge if checks pass

---

Adaptation Examples

Example 1: Startup (Move Fast)

Team: 2 developers, 1 designer

Customization:

# Minimal agents
.claude/agents/
├── planner.md       # Quick requirements
└── fullstack.md     # Combined FE/BE developer

# 2-phase workflow
1. Planning (30 min)
2. Implementation (until done)

# No ClickUp
# Session files only

# No formal QA
# Manual testing by developers

# No code review
# Pair programming instead

Benefits:

• Fast iteration
• Low overhead
• Flexible approach

Example 2: Enterprise (Quality First)

Team: 10 developers, 2 QA, 1 security specialist

Customization:

# Full agent suite + custom
.claude/agents/
├── product-manager.md
├── architecture-supervisor.md
├── frontend-developer.md
├── backend-developer.md
├── mobile-developer.md
├── security-specialist.md    # Custom
├── qa-tester.md
├── code-reviewer.md
└── documentation-writer.md

# 6-phase workflow
1. Requirements (PM)
2. Architecture (Supervisor)
3. Development (FE/BE/Mobile)
4. Security Review (Security Specialist)
5. QA Testing (QA Team)
6. Code Review (Lead Developers)

# ClickUp + Jira
# Dual tracking for compliance

# Comprehensive testing
# Unit + Integration + E2E + Security

# Mandatory code review
# 2 approvals required

Benefits:

• High quality
• Compliance ready
• Audit trail
• Scalable process

Example 3: Agency (Client Projects)

Team: 5 developers, varies by project

Customization:

# Project-specific agents
.claude/agents/
├── product-manager.md
├── architect.md
├── developer.md              # Generalist
├── qa-tester.md
└── client-liaison.md         # Custom

# Flexible workflow
1. Client Requirements (PM + Liaison)
2. Proposal (Architect)
3. Implementation (Developers)
4. Client Review (Liaison)
5. Final QA
6. Delivery

# GitHub Issues per client
# Client-specific configurations

# Varied testing
# Based on client requirements

# Client approval
# Before final delivery

Benefits:

• Client-focused
• Flexible per project
• Clear communication
• Professional delivery

Example 4: Open Source (Community)

Team: Distributed contributors

Customization:

# Public agents
.claude/agents/
├── contributor.md     # For external contributors
├── maintainer.md      # For core team
└── reviewer.md        # For review team

# Contribution workflow
1. Issue discussion (GitHub)
2. Implementation (Contributor)
3. PR review (Maintainer)
4. Merge

# GitHub Issues + Discussions
# Public tracking

# Automated testing
# CI/CD pipeline

# Community review
# 1-2 maintainer approvals

Benefits:

• Open and transparent
• Community friendly
• Automated checks
• Clear process

---

Configuration Templates

Solo Developer Template

# .claude/config/agents.md
## Project Type
Solo Developer

## Agents Used
- planner (for complex features)
- developer (primary)

## Workflow
1. Planning (optional)
2. Implementation
3. Self-review

## Tools
- No ClickUp
- Git for tracking
- Session files for history

Small Team Template

# .claude/config/agents.md
## Project Type
Small Team (3 developers)

## Agents Used
- product-manager
- architecture-supervisor
- developer (shared role)
- qa-tester

## Workflow
1. Requirements (PM)
2. Planning (Architect)
3. Development (Developers)
4. QA (QA or developer)

## Tools
- GitHub Issues
- Session files
- Slack for coordination

Enterprise Template

# .claude/config/agents.md
## Project Type
Enterprise (20+ developers)

## Agents Used
- Full agent suite
- Custom security agent
- Custom devops agent

## Workflow
- 6-phase waterfall
- Formal handoffs
- Comprehensive documentation

## Tools
- Jira
- ClickUp
- Confluence
- Session files for technical detail

---

Best Practices for Customization

Start Simple

✅ DO:

• Start with minimal setup
• Add complexity as needed
• Test changes with small features
• Document your customizations

❌ DON'T:

• Over-engineer from the start
• Add all possible features
• Change everything at once
• Forget to document changes

Iterate

Week 1: Use default workflow, observe pain points
Week 2: Simplify one area (e.g., remove unused agents)
Week 3: Add one custom feature (e.g., custom command)
Week 4: Refine based on team feedback

Document Your Workflow

Create team-specific documentation:

# docs/our-workflow.md
# Our Team's Claude Workflow

## Agents We Use
- planner (requirements + architecture)
- developer (implementation)
- qa (testing)

## Our Process
1. Create issue in GitHub
2. Run /init-task
3. Implement
4. Self-review
5. Merge

## Custom Commands
- /quick-task - Fast feature workflow
- /bug-fix - Bug fix workflow

## Team Conventions
- Session naming: use-feature-name format
- Always update progress file
- Add context entry when switching phases

Get Team Buy-In

Tips:

• Show benefits with real examples
• Start with volunteers
• Iterate based on feedback
• Make it optional initially
• Prove value before mandating

---

Troubleshooting Customizations

Problem: Custom agent not working

Solution:

• Check agent file syntax
• Verify tools are available
• Test with simple task
• Review agent file frontmatter

Problem: Custom command fails

Solution:

• Verify command file format
• Check agent references are correct
• Test each phase independently
• Add error handling

Problem: Team not adopting workflow

Solution:

• Simplify further
• Show concrete benefits
• Make it easier than current process
• Provide training/examples
• Get feedback and iterate

---

Next Steps

For Your Team

1. Assess Current State

   • How do you work now?
   • What pain points exist?
   • What would help most?

2. Start Small

   • Pick one area to customize
   • Test with one feature
   • Gather feedback

3. Iterate

   • Add complexity gradually
   • Remove what doesn't work
   • Document what works

4. Scale

   • Roll out to team
   • Create team documentation
   • Establish conventions

Additional Resources

• Introduction - Understand core concepts
• Agents - Learn about agents
• Commands - Create custom commands
• ClickUp Integration - Adapt to other tools

---

Remember: The best workflow is the one your team actually uses. Customize freely, iterate constantly, and optimize for your specific needs.