Building a Task Management System with Claude Code

How I streamlined complex feature development with custom commands

After spending a few months working with Claude Code on a complex web application, I found myself doing the same dance: reading Linear issues, breaking them down into implementable chunks, then carefully coordinating changes across our API, web app, and background workers.

The manual process was consuming time I'd rather spend on architectural decisions and solving interesting problems. So I built a two-command workflow that handles the systematic parts, letting me focus on the parts that need human insight.

The Challenge: Real Codebases Are Messy

Working on any substantial application means dealing with:

• 50+ interconnected files across services
• Architectural patterns that need consistency
• Background workflows (we use Temporal.io)
• Database migrations and API changes
• Testing requirements across different components
• Integration between Linear, GitHub, and our deployment pipeline

The gap between "here's a Linear issue" and "here's a working feature" involves a lot of systematic work that's important but not particularly creative.

The Solution: Two Custom Commands

I ended up building two commands that work together:

breakdown-linear-issue - Task Decomposition

This command reads a Linear issue and creates an implementation plan. It's essentially automating the analysis phase I was doing manually:

• Parses the issue description and acceptance criteria
• Maps requirements to our codebase structure
• Identifies which files and services need changes
• Creates a sequence of implementable tasks
• Notes testing requirements and potential complications

The output is a markdown file with specific tasks that can be tackled independently.

process-task - Implementation

This command takes one of those task files and implements it:

• Reads the task specification
• Analyses the current state of relevant files
• Makes the necessary changes while following our code patterns
• Runs tests and fixes fundamental issues
• Creates a commit with a descriptive message

The key insight was separating planning from execution. Planning requires understanding the full context, while execution benefits from focused attention on one piece at a time.

A Real Example: Adding Email Notifications

Let me show you how this works with a real feature I implemented last month.

Linear Issue: "Users should receive email alerts when certain conditions are met, with different notification frequencies for different subscription tiers."

Step 1: Strategic Breakdown

/breakdown-linear-issue DEV-123

The command analysed our codebase and identified that this wasn't just "add email sending." It involved:

• Database schema changes (notification thresholds, user preferences)
• Temporal workflow modifications (our background job system)
• API endpoints for managing notifications
• Email template system integration
• Subscription tier validation
• Rate limiting for different user types
• Frontend components for notification management
• Comprehensive testing across all components

It generated 8 distinct tasks with clear dependencies and an estimated scope.

Step 2: Systematic Execution

/process-task implement-notification-database-schema
/process-task implement-notification-workflow-system
/process-task implement-notification-api-endpoints
# ... and so on

Each command executed its part while maintaining awareness of the overall system. When implementing the API endpoints, it automatically used our existing auth middleware, validation patterns, and error handling conventions.

Why This Works

1. Architectural Awareness

The commands understand our specific patterns:

• Fastify + Prisma + Temporal.io stack
• Auth0 integration patterns
• Service abstraction layers
• Testing requirements (>50% API coverage, >90% service coverage)

2. Context Preservation

Unlike chatting with an AI that forgets context, these commands maintain awareness of:

• What's already implemented
• What other changes are in flight
• How does this feature fit into the larger roadmap
• Our specific code quality requirements

3. Execution Discipline

The two-step process prevents the classic engineering mistake: jumping into implementation before understanding the problem. The breakdown phase forces me to think through the complete scope.

The Meta-Workflow: How I Use These Together

Here's my typical development cycle:

1. Linear issue created (usually by PM or from user feedback)
2. Strategic analysis: breakdown-linear-issue to understand full scope
3. Review and refine: I review the breakdown, adjust priorities, maybe split into smaller issues
4. Systematic implementation: process-task for each sub-task
5. Integration testing: Run our E2E test suite
6. Code review: Create PR with comprehensive context

The key insight: I'm not trying to replace engineering judgment, I'm systematising the execution of that judgment.

The Technical Implementation (For Fellow Engineers)

These commands work through Claude Code's MCP (Model Context Protocol) integrations:

• Linear API: Direct integration for reading issue details, updating status
• GitHub API: For managing branches, PRs, and code analysis
• Context memory: Maintains understanding across command invocations

The commands aren't just scripts - they're AI workflows that understand our specific codebase patterns and can adapt to changing requirements.

How Well Does It Work?

After using this system for a while, I've got some data on its effectiveness. The results are mixed but generally positive.

Task Breakdown Quality (breakdown-linear-issue)

What I track: I compare the initial breakdown with the actual implementation. Did we miss major components? Were the estimates reasonable?

Success rate: About 95% of breakdowns are accurate enough to execute without significant revisions. The remaining 5% usually miss one of two things:

• Edge cases that become apparent during implementation
• Dependencies on other systems that weren't obvious from the Linear issue

Common failures:

• Underestimating frontend complexity (exceptionally responsive design edge cases)
• Missing auth/permission implications

What works well: Database schema changes, API endpoint structure, testing scope. The command is surprisingly good at identifying all the files that need changes.

Implementation Quality (process-task)

What I track: How much of the generated code makes it to production without modification, test pass rates, and code review feedback.

First-pass success rate: About 85% of implementations work correctly on the first try. Another 10% need minor fixes (missing imports, test adjustments). The remaining 5% need significant rework.

Second-pass improvement: For code that doesn't pass on first try, running it through Gemini's code review and debugging tools brings the success rate to nearly 95%. Most issues are caught and fixed automatically.

Where it excels:

• Following our existing patterns (auth middleware, validation, error handling)
• Creating comprehensive tests that test the right things
• Maintaining consistency across similar components

Where it struggles:

• UI/UX details that aren't well-specified in the task breakdown

Measuring Impact

I started tracking these metrics after the first month:

Development velocity:

• Before: ~1.5 features per week (simple) to 1 feature per 2 weeks (complex)
• After: ~2 features per week (simple) to 1.2 features per week (complex)
• The biggest gain is in medium-complexity features

Code review cycles:

• Before: 2.3 review cycles average before merge
• After: 1.7 review cycles average
• Fewer "you forgot to update the tests" type comments

Production bugs:

• No significant change in bug rate, but bugs tend to be more focused (business logic issues rather than integration problems)

The Reality Check

The system isn't magic. It's more like having a very thorough junior developer who:

• Never gets tired of following checklists
• Has perfect memory of our code patterns
• Sometimes misses the forest for the trees
• Needs precise specifications to produce good work

The biggest value is consistency and thoroughness, not brilliance.

The Bigger Picture

This isn't about AI taking over programming. It's about elevating the level of problems we solve.

Instead of spending cycles on:

• "How do I structure this API endpoint?"
• "What files need to change for this feature?"
• "Did I remember to update all the tests?"

I can focus on:

• "What's the right user experience here?"
• "How does this feature fit into our product strategy?"
• "What's the most maintainable architecture for this?"

Getting Started With Your Workflow

If you want to build something similar:

1. Start with your pain points - What repetitive decisions do you make? What do you always forget?
2. Codify your patterns - Document your architectural decisions, coding standards, and testing requirements
3. Build incrementally - Start with simple commands, add complexity as you learn
4. Measure the impact - Track velocity, bug rates, consistency metrics

The goal isn't to build the fanciest AI system. It's to build something that makes you a more effective engineer.

Conclusion

Claude Code isn't magic. But when you invest the time to teach it your specific patterns and build systematic workflows, it becomes incredibly powerful.

The commands I've built aren't just productivity tools - they're a way to encode and scale engineering best practices. They help me be more systematic, more thorough, and more consistent.

And honestly? After 20+ years of writing code, anything that helps me focus on the interesting problems instead of the repetitive ones is a win.

This workflow is tailored to my team's specific needs and technical stack. The principles (systematic breakdown, architectural awareness, execution discipline) are universal, but the implementation details will vary for your context.*

Want to see more about how these commands work? I'm considering open-sourcing the command definitions and sharing more detailed implementation guides.