Skip to main content

Command Mode User Guide

Table of Contents​

  1. Introduction
  2. Why Specificity Matters
  3. Command Structure Best Practices
  4. Common Command Categories
  5. Examples: Good vs Bad Commands
  6. Advanced Tips
  7. Troubleshooting

Introduction​

Command Mode is a powerful feature that allows you to update your project documentation using natural language commands. However, the quality of the updates depends heavily on how clearly and specifically you express your requirements.

This guide will help you write effective commands that produce accurate, comprehensive documentation updates.

Why Specificity Matters​

When you issue a vague command like "use AWS for hosting," the AI must make assumptions about:

  • Which AWS service you mean (EC2, Lambda, S3, ECS, etc.)
  • What type of hosting (static files, API, full application, database)
  • Your deployment preferences (serverless, containers, VMs)
  • Cost and scaling requirements

These assumptions may not align with your actual needs, leading to documentation that doesn't match your intended architecture.

Command Structure Best Practices​

1. Be Specific About Technology Choices​

❌ Bad: "Use AWS for hosting"
✅ Good: "Use AWS Lambda for API endpoints and S3 for static file hosting"

❌ Bad: "Add authentication"
✅ Good: "Add JWT-based authentication using Supabase Auth with email/password and Google OAuth"

2. Include Context and Requirements​

❌ Bad: "Switch to PostgreSQL"
✅ Good: "Switch from MongoDB to PostgreSQL for better relational data modeling and support for complex queries with joins"

3. Specify Integration Points​

❌ Bad: "Add payment processing"
✅ Good: "Add Stripe payment processing for subscription billing with webhook integration for payment events"

4. Define Scope Clearly​

❌ Bad: "Improve performance"
✅ Good: "Add Redis caching for frequently accessed user data and implement database query optimization for the dashboard analytics"

5. Understanding Replacement vs Migration Commands​

Important: By default, all projects are treated as being in the documentation phase. This means replacement commands will completely replace old technologies without preserving historical context.

Default Behavior (Complete Replacement):

  • "Use Stripe instead of PayPal" → All PayPal references will be replaced with Stripe
  • "Remove all mentions of MongoDB" → MongoDB will be completely removed from all documents
  • The documentation will be written as if the new technology was always the choice

When Historical Context is Preserved: Only when you explicitly request it:

  • "Migrate from PayPal to Stripe" → Will include migration notes
  • "Replace MongoDB with PostgreSQL and keep migration notes" → Will preserve historical context
  • "Switch to Stripe but document the migration process" → Will include transition details

Examples:

  • ✅ Complete Replacement: "Use Supabase instead of Firebase"
  • ✅ With Migration Context: "Migrate from Firebase to Supabase with migration steps"

Common Command Categories​

1. Technology Stack Changes​

Template: "Replace [current technology] with [new technology] for [specific purpose]"

Examples:

  • "Replace Express.js with Fastify for the REST API to improve performance"
  • "Switch from Create React App to Next.js for server-side rendering and better SEO"
  • "Use Prisma ORM instead of raw SQL queries for type-safe database access"

2. Complete Replacements vs Migrations​

Complete Replacement Template: "Use [new technology] instead of [old technology]"

  • Results in complete removal of old technology
  • Documentation written as if new technology was always used
  • No historical references preserved

Migration Template: "Migrate from [old technology] to [new technology]"

  • Includes migration steps and considerations
  • May preserve some historical context
  • Documents the transition process

Removal Template: "Remove all mentions of [technology/feature]"

  • Completely removes all references
  • Updates all affected documents
  • No traces left of the removed item

3. Feature Additions​

Template: "Add [feature name] that allows users to [specific functionality] using [technology/approach]"

Examples:

  • "Add real-time chat feature using Socket.io that allows users to send direct messages and create group conversations"
  • "Implement file upload functionality using AWS S3 with presigned URLs for secure direct browser uploads"
  • "Add two-factor authentication using TOTP (Time-based One-Time Passwords) with QR code setup"

4. Architecture Changes​

Template: "Restructure [component/system] to use [pattern/architecture] for [benefit]"

Examples:

  • "Restructure the backend to use microservices architecture with separate services for auth, payments, and core business logic"
  • "Implement event-driven architecture using AWS SQS for asynchronous processing of heavy tasks"
  • "Add a GraphQL API layer alongside the REST API for more efficient data fetching in the mobile app"

5. Integration Updates​

Template: "Integrate [service/API] for [purpose] with [specific configuration]"

Examples:

  • "Integrate SendGrid API for transactional emails with templates for welcome, password reset, and order confirmation"
  • "Add Sentry error tracking for both frontend and backend with custom error boundaries and user context"
  • "Integrate Algolia search for product catalog with faceted search and instant search UI components"

6. Security Enhancements​

Template: "Implement [security measure] to protect against [threat/vulnerability]"

Examples:

  • "Implement rate limiting using Redis to prevent API abuse with limits of 100 requests per minute per user"
  • "Add input validation and sanitization using Joi schemas to prevent SQL injection and XSS attacks"
  • "Implement API key authentication for third-party integrations with key rotation every 90 days"

Examples: Good vs Bad Commands​

Database Updates​

❌ Vague: "Update the database"

  • Unclear what needs updating
  • No context about why

✅ Specific: "Add indexes to the users table on email and created_at columns to optimize login queries and user listing performance"

  • Clear action (add indexes)
  • Specific location (users table)
  • Exact columns specified
  • Purpose explained

API Changes​

❌ Vague: "Make the API better"

  • No actionable information
  • "Better" is subjective

✅ Specific: "Implement API versioning using URL path versioning (e.g., /api/v1/) and add pagination to all list endpoints using cursor-based pagination"

  • Clear implementation strategy
  • Specific versioning approach
  • Defined pagination method

Frontend Updates​

❌ Vague: "Improve the UI"

  • Too broad
  • No specific direction

✅ Specific: "Implement a dark mode theme using CSS variables and localStorage for persistence, with a toggle switch in the header"

  • Clear feature (dark mode)
  • Technical approach defined
  • User interaction specified

Deployment Changes​

❌ Vague: "Deploy to the cloud"

  • Many cloud providers exist
  • Deployment method unclear

✅ Specific: "Deploy the application using Docker containers on AWS ECS with auto-scaling based on CPU usage and a load balancer for high availability"

  • Specific cloud provider (AWS)
  • Deployment technology (Docker, ECS)
  • Scaling strategy defined
  • Infrastructure requirements clear

Advanced Tips​

Instead of one complex command, break it into logical steps:

First command: "Replace the current SQLite database with PostgreSQL for production use"

Second command: "Add database migration scripts using Knex.js to manage schema changes"

Third command: "Implement connection pooling with pg-pool for the PostgreSQL database with a maximum of 20 connections"

2. Provide Business Context​

Help the AI understand the "why" behind your changes:

Good example: "Add multi-tenant support using subdomain-based tenant identification because we need to serve multiple clients with isolated data"

This context helps generate more relevant implementation details.

3. Specify Non-Functional Requirements​

Include performance, security, or scalability requirements:

Example: "Implement image upload with automatic resizing to 3 sizes (thumbnail: 150x150, medium: 800x600, large: 1920x1080) and WebP conversion for better performance"

4. Reference Existing Patterns​

If you want consistency with existing code:

Example: "Add a user profile API endpoint following the same RESTful patterns and error handling as the existing auth endpoints"

Troubleshooting​

Problem: Updates are too generic​

Solution: Add more specific technical details and constraints

  • Mention specific libraries or frameworks
  • Include version requirements
  • Specify configuration details

Problem: Updates miss important integration points​

Solution: Explicitly mention what needs to connect

  • List all affected systems
  • Specify data flow between components
  • Include API contracts or interfaces

Problem: Updates don't match your coding style​

Solution: Provide style preferences in your command

  • Mention naming conventions
  • Specify architectural patterns you follow
  • Reference existing code patterns

Problem: Updates are too complex for your needs​

Solution: Add constraints to your command

  • Specify "simple" or "minimal" implementation
  • Set boundaries on scope
  • Mention what NOT to include

Command Templates​

Use these templates as starting points:

For New Features​

Add [feature name] that enables [user action] by implementing [technical approach] with [specific requirements/constraints]

For Technology Changes​

Replace [current tech] with [new tech] in [specific component] to achieve [goal] while maintaining compatibility with [existing system]

For Integrations​

Integrate [service name] for [purpose] using [authentication method] with support for [specific features] and error handling for [failure scenarios]

For Performance Improvements​

Optimize [component/feature] by implementing [optimization technique] to achieve [performance goal] measured by [metric]

For Security Updates​

Secure [component/data] by implementing [security measure] following [standard/best practice] to prevent [threat/vulnerability]

Best Practices Summary​

  1. Be Specific: Name exact technologies, services, and approaches
  2. Provide Context: Explain why you're making the change
  3. Set Boundaries: Define what should and shouldn't be included
  4. Think Step-by-Step: Break complex changes into smaller commands
  5. Include Examples: When applicable, provide examples of desired behavior
  6. Specify Integrations: Clearly state what needs to connect with what
  7. Define Success Criteria: Help the AI understand what "done" looks like

Remember: The more specific and detailed your command, the better the resulting documentation updates will be. When in doubt, err on the side of providing too much information rather than too little.