Every week, I run small experiments with context-driven development (CDD), AI tools, and imdone-cli - a tool I built that keeps your backlog right in your source code so you never lose context.
This week, I'm putting Claude Code to the test on a critical developer experience improvement: normalizing imdone-cli commands to follow Git-like conventions. When CLI tools have inconsistent argument patterns, developers waste mental energy figuring out syntax instead of solving problems.
Why CLI Consistency Matters
As imdone-cli evolved, command arguments became inconsistent. The template command required verbose options:
imdone template --issue-key SCRUM-123 --template bug
But developers expect familiar Git-like patterns:
git commit -m "message" # Positional arguments
imdone template SCRUM-123 bug # Much cleaner
This inconsistency creates cognitive friction. By normalizing to Git conventions, we reduce mental overhead to zero.
The Context-Driven Development Approach
I structured this task using templates in Imdone:
Goal: Normalize the template command to use positional arguments, accept them in any order, and provide intuitive aliases.
Constraints:
- Use TDD with red-green-refactor cycle
- Follow de facto CLI standards (Git-like)
- Update documentation automatically
- Don't break existing functionality
Files: Links to entry point, test files, and command patterns.
This template-based approach means I can quickly spin up well-structured tasks. Just type $ in VS Code with the Imdone extension, select my template, and I have a complete spec ready for Claude.
The Development Journey
01:46 - Template-Based Setup
I demonstrated my workflow using Imdone templates to structure AI tasks. The spec lives as markdown synced with Jira, so teammates see the same information without context-switching.
Lesson learned: File linking requires a leading slash (/cli-package/src/bin.mjs) for proper navigation.
03:05 - Handling Merge Conflicts
When I ran imdone push to sync updates, I hit a merge conflict. imdone-cli handles this with git-like merge resolution:
imdone push # Triggers conflict
imdone merge # Completes merge
Key feature: Multiple team members can work on the same issue simultaneously - something Jira doesn't allow.
07:11 - Claude Implements TDD
I prompted: "Execute the task on line 21." That's it. Claude understood everything from the context file.
While Claude worked, I explained my .claude/rules folder where I keep context files for homepage strategies, pair programming experts, and writing constraints. These ensure Claude has domain knowledge about my projects.
Claude generated comprehensive tests:
describe('template command', () => {
it('should apply template to existing issue', async () => {})
it('should work with alias t instead of template', async () => {})
it('should accept issue and template in any order', async () => {})
})
10:35 - Teaching Red-Green-Refactor
Initial tests passed when they should have failed - Claude implemented everything at once instead of following TDD discipline.
This is a common AI mistake: They're too helpful and skip the red phase.
I added: "Use red-green-refactor cycle. Tests should fail before implementation."
After some back-and-forth, Claude understood. It wrote failing tests first, confirmed they failed, then implemented the feature.
13:04 - Tests Failing (Good!)
npm test
❌ should accept issue and template in any order
❌ should work with alias t
Perfect. This is exactly what we want in TDD.
13:28 - Implementation
Claude updated the command structure:
// Old way
.option('--issue-key <key>', 'Issue key')
.option('--template <name>', 'Template name')
// New way (positional arguments)
.argument('[issue]', 'Issue key')
.argument('[template]', 'Template name')
.alias('t')
Clean, logical, and follows commander.js conventions.
16:45 - All Tests Pass
✅ All 14 tests passing
The command now follows Git patterns:
# Before (awkward)
imdone template --issue-key SCRUM-123 --template bug
# After (Git-like)
imdone template SCRUM-123 bug
imdone t SCRUM-123 bug # with alias
19:00 - Proactive Analysis
Without prompting, Claude suggested: "Would you like me to normalize the update command? It uses --force without a corresponding -f short option."
This kind of codebase-wide pattern recognition is where AI assistants shine.
24:42 - Manual Testing Success
npm run build
npm link
imdone template SCRUM-138 story
The command accepted positional arguments and felt natural - no mental friction about syntax.
Key Takeaways
What Worked Well
Template-Based Specs: Having a reusable template with files, goals, and constraints meant Claude had everything upfront. No back-and-forth.
TDD Discipline: Once Claude understood red-green-refactor, it followed perfectly. Tests documented desired behavior, failed appropriately, then passed after implementation.
Proactive Pattern Recognition: Claude spotted other commands needing normalization without being asked.
Challenges and Real-World Friction
AI Over-Helpfulness: Initially, Claude implemented features while writing tests instead of following TDD. Required explicit guidance about red-green-refactor.
Test Philosophy Confusion: Claude initially wrote test descriptions mentioning "should fail" rather than describing desired behavior. Took iteration to clarify.
Waiting Time: Moments where you're just waiting for AI to generate code (30-60 seconds) - enough to break flow slightly.
When to Use AI Assistants for Refactoring
AI coding assistants excel at:
- Following established patterns across a codebase
- Writing comprehensive tests for new behavior
- Updating documentation consistently
- Spotting similar patterns elsewhere
They need guidance with:
- TDD discipline (will skip red-green-refactor if not reminded)
- Understanding test philosophy
- Making architectural decisions
The Bigger Picture: Developer Experience
Consistency reduces cognitive load.
When every CLI tool invents its own syntax, developers spend mental energy on syntax instead of problems. When tools follow de facto standards (Git, npm, docker), they feel immediately familiar.
This is what imdone-cli enables more broadly: keeping context (backlog, decisions, discussions) right next to code reduces context-switching overhead. Same principle, different domains.
Try It Yourself
-
Install imdone-cli:
npm install -g imdone-cli -
Set up templates: Create templates in
.imdone/templates/for common patterns - Structure AI tasks: Include goals, constraints, and file references
- Use TDD explicitly: Specify "red-green-refactor" in constraints
- Iterate and learn: AI assistants need guidance around testing discipline
What's Next?
Upcoming features:
- Favorites system: Organize large issue lists into folders (requested by my 40-person team)
- Desktop integration: Open Imdone Desktop from CLI
- Maybe ensemble programming with Claude as part of the team?
Join the Conversation
Have you normalized CLI commands in your projects? Used Claude Code for refactoring?
Drop a comment below with:
- Patterns you've discovered for teaching AI assistants about TDD
- CLI design decisions you've made (or regretted)
- How you structure tasks for AI coding assistants
If you found this useful, give it a ❤️ and follow me for weekly experiments at the intersection of AI, developer experience, and better tooling.
Video Timeline
- 00:00 - Introduction to weekly CDD experiments
- 00:16 - Decision to normalize CLI commands
- 01:46 - Setting up with Imdone templates
- 03:05 - Handling merge conflicts
- 07:11 - Claude implements with TDD
- 10:35 - Teaching red-green-refactor
- 13:04 - Tests failing (good!)
- 13:28 - Implementation passes tests
- 16:45 - All tests green
- 19:00 - Claude suggests more improvements
- 24:42 - Manual testing success
- 26:16 - Planning next release
- 28:06 - Preview: favorites feature
This post is part of my weekly context-driven development experiment series. Check out previous experiments and follow along as I explore better ways to build software with AI assistance.
Top comments (0)