Best Practices

This guide shares proven strategies and patterns from experienced Dropstone Agent users to help you maximize productivity and code quality.

Communication Best Practices

1. Be Specific, But Don't Overthink It

Less Effective:

"Update the code"

Better:

"Add error handling to the fetchUsers function"

Best:

"Add try-catch error handling to fetchUsers in src/api/users.ts.
Log errors and return a user-friendly message."

But Remember: Even simple requests work! The agent will ask clarifying questions if needed.

2. Provide Context with @ Mentions

Without Context:

"Create a similar component"

With Context:

"@src/components/Button.tsx Create a similar Input component"

The Difference:

• Without: Agent makes assumptions or asks questions
• With: Agent follows exact patterns immediately

Context Types:

• @file - Show examples to follow
• @folder - Give context about related code
• @url - Include external documentation
• @problems - Reference VS Code errors
• @terminal - Include command output

3. Use Iterative Development

Build features through conversation, not all at once.

Instead of:

"Create a complete user management system with authentication,
authorization, profile editing, password reset, email verification,
two-factor authentication, and admin dashboard"

Try:

Step 1: "Create basic user authentication with login and registration"
[Review implementation]

Step 2: "Add password reset functionality"
[Review implementation]

Step 3: "Add email verification"
[Continue iterating...]

Benefits:

• Catch issues early
• Adjust direction as needed
• Learn gradually
• Better code review

4. Leverage Conversation History

The agent remembers your conversation. Build on it!

You: "Create a User API endpoint"
Agent: [Creates endpoint]

You: "Add input validation"
Agent: [Adds validation]

You: "Add rate limiting"
Agent: [Adds rate limiting]

You: "Now create a similar endpoint for Posts"
Agent: [Creates Posts endpoint with validation AND rate limiting]

Code Quality Practices

1. Always Use Version Control

Before Major Changes:

git add .
git commit -m "Before agent changes"

Why:

• Easy rollback if needed
• See exactly what changed
• Compare before/after
• Confidence to experiment

2. Enable Checkpoints

In Settings:

Settings → Checkpoint Settings → Enable Checkpoints

What It Does:

• Creates automatic snapshots
• Easy rollback to any point
• No need to commit constantly

When to Use:

• Experimental features
• Large refactorings
• Learning new patterns
• High-risk changes

3. Review Before Approving

For Write Operations:

• Check file paths carefully
• Review code changes in diffs
• Verify this is what you want
• Consider side effects

Red Flags:

❌ Deleting many files at once
❌ Changes to configuration files without review
❌ Modifying files outside project folder
❌ Running unfamiliar commands

4. Start Conservative with Auto-Approve

Recommended Progression:

Week 1: Manual Everything

☐ Auto-approve read operations
☐ Auto-approve write operations
☐ Auto-approve commands

Learn how the agent works.

Week 2-3: Enable Safe Operations

☑ Auto-approve read operations
☐ Auto-approve write operations
☐ Auto-approve commands

Reading files is safe.

Month 2+: Selectively Enable More

☑ Auto-approve read operations
☑ Auto-approve file modifications (in specific folders)
☐ Auto-approve file deletion
☑ Auto-approve allowed commands

Based on your comfort level.

5. Use the Right Mode for the Task

Quick Reference:

Let Agent Choose: In most cases, let the agent auto-select the mode.

Project-Specific Practices

1. Establish Patterns Early

First API Endpoint: Be explicit about your preferences

"Create a users API endpoint with:
- RESTful routes
- Joi validation
- Try-catch error handling
- Standardized JSON responses
- JWTauthentication
- Jest tests with 80%+ coverage

Use this pattern for all future endpoints."

Result: Future endpoints automatically follow this pattern.

2. Create a Project Style Guide

Share with Agent:

@docs/STYLE_GUIDE.md

"Always follow the patterns in this style guide when
creating new code."

Or Use Instructions File:

@.dropstone/instructions.md

"Fetch instructions from this file before starting tasks"

3. Use Consistent File Organization

Good Structure:

src/
├── features/
│   ├── users/
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   ├── users.model.ts
│   │   └── users.test.ts
│   └── posts/
│       ├── posts.controller.ts
│       ├── posts.service.ts
│       ├── posts.model.ts
│       └── posts.test.ts

Why:

• Agent learns the pattern quickly
• New features follow structure automatically
• Easy navigation
• Clear organization

4. Maintain Test Coverage

Make It a Requirement:

"Always generate tests when creating new functions.
Aim for 80%+ coverage."

Agent Will:

• Generate tests automatically
• Follow your testing patterns
• Include edge cases
• Run tests after changes

Performance Practices

1. Break Large Tasks into Smaller Ones

Instead of:

"Refactor the entire codebase to use TypeScript"

Try:

"Convert files in src/utils/ to TypeScript"
[Review]

"Convert src/models/ to TypeScript"
[Review]

"Convert src/services/ to TypeScript"
[Continue...]

Benefits:

• Faster individual tasks
• Earlier feedback
• Easier to verify
• Can stop anytime

2. Use Specific Paths

Slow:

"Find all API endpoints"
[Agent searches entire project]

Fast:

"@src/routes Show me all API endpoints"
[Agent only searches routes folder]

3. Leverage Learned Patterns

After the agent learns your patterns:

First Time (Slow):

"Create an API endpoint for users"
Time: 5 minutes, Multiple approvals

After Learning (Fast):

"Create an API endpoint for posts"
Time: 1 minute, Autonomous execution

Security Practices

1. Never Auto-Approve Sensitive Operations

Keep Manual Approval For:

• Environment variable changes
• Security configurations
• Authentication logic
• Authorization rules
• Database migrations
• Deployment scripts

2. Review Generated Secrets

Be Careful With:

❌ API keys in code
❌ Passwords in config
❌ Tokens hardcoded
❌ Private keys committed

Agent knows not to, but always verify:

"Add database config using environment variables,
not hardcoded credentials"

3. Validate Security-Critical Code

Always Review:

• Authentication implementations
• Authorization checks
• Input validation
• SQL queries (injection risks)
• File upload handling
• API security

Ask for Security Review:

"Review this authentication code for security issues"

Collaboration Practices

1. Share Learned Patterns with Team

Export Patterns:

Settings → Learning → Export Patterns
→ patterns.json

Team Member Imports:

Settings → Learning → Import Patterns
→ Select patterns.json

Result: Entire team benefits from learned patterns.

2. Use Shared Workspaces

For Team Projects:

More Menu → Create Shared Workspace
→ Share workspace ID with team

Benefits:

• Shared task history
• Collaborative learning
• Consistent patterns
• Team knowledge base

3. Document Agent Patterns

In README:

## Working with Dropstone Agent

### Our Patterns
- API endpoints follow RESTful conventions
- Use Joi for validation
- Error handling with try-catch
- Tests required for all features

### Asking the Agent
- Good: "Create a new feature endpoint"
- Agent knows our patterns and will apply them

Troubleshooting Practices

1. Provide Error Details

Minimal:

"It's not working"

Better:

"The login function returns undefined"

Best:

"@mode debug
The login function in src/auth/login.ts returns undefined
when I call it with valid credentials.

@terminal
[Paste error from console]

Expected: Return user object
Actual: undefined

2. Use Debug Mode Effectively

When Things Break:

@mode debug

"After my last change, tests are failing.
The tests were passing before I modified the User model.

Changes I made:
- Added email field to User
- Updated validation

Failing tests:
@problems

3. Reference Past Successful Tasks

When Stuck:

"In Task #47, we successfully implemented user authentication.
I need similar authentication for the admin panel.
Can you replicate that approach?"

Learning Practices

1. Confirm Successful Patterns

When Agent Does Well:

"Perfect! That's exactly the pattern we use.
Apply this same structure to all future components."

Result: Agent confidence increases for similar tasks.

2. Correct Mistakes Early

When Agent Does It Wrong:

"This works, but it's not our standard approach.
We always put validation in separate middleware files,
not inline in routes. Please refactor."

Result: Agent learns correct pattern, avoids in future.

3. Provide Context for Decisions

Explain WHY:

"We use this error handling pattern because:
1. It provides consistent error responses
2. Easier to debug with centralized logging
3. Simpler to add monitoring later

Always use this pattern."

Result: Agent understands rationale, applies thoughtfully.

4. Review Learned Patterns Regularly

Monthly Check:

Settings → Learning → View Patterns

Review patterns:
✓ Are they still relevant?
✓ Any outdated approaches?
✓ Missing important patterns?

Delete/update as needed.

Advanced Practices

1. Use Multiple Modes in Sequence

Complex Workflow:

Step 1: "@mode architect
Design the notification system"
[Review architecture]

Step 2: "@mode code
Implement the design from step 1"
[Review implementation]

Step 3: "@mode ask
Explain how I should deploy this"

2. Create Reusable Patterns

Example Pattern File:

// .dropstone/patterns/api-endpoint.ts

/**
 * Standard API Endpoint Pattern
 *
 * Structure:
 * - Route with validation middleware
 * - Controller with try-catch
 * - Service with business logic
 * - Model with schema
 * - Tests with 80%+ coverage
 */

// Tell agent: "Use this pattern for all API endpoints"

3. Optimize Repetitive Tasks

Create Shortcuts:

"When I say 'new feature', I mean:
1. Create feature folder structure
2. Add controller, service, model files
3. Generate tests
4. Update routes/index.ts
5. Add to API documentation"

Anti-Patterns to Avoid

❌ Don't: Give Vague Instructions

❌ "Make it better"
❌ "Fix the bugs"
❌ "Optimize everything"

❌ Don't: Ignore Warnings

❌ Approving file deletions without checking
❌ Skipping code review
❌ Disabling all approval requests immediately

❌ Don't: Treat It Like a Search Engine

❌ "What is React?"
   (Use web search or documentation)

✓ "@src/components/App.tsx
   How does this component work in our app?"
   (Contextual question about YOUR code)

❌ Don't: Make Every Change at Once

❌ "Refactor everything, add tests, update docs,
    upgrade dependencies, and add new features"

✓ "Let's start with refactoring the user service"
   [One thing at a time]

❌ Don't: Skip Context

❌ "Add validation"
   (Which file? What kind? Where?)

✓ "@src/api/users.ts
   Add Joi validation to the createUser function"

Quick Win Checklist

Day 1:

• Enable version control
• Review approval settings
• Try simple tasks to build trust

Week 1:

• Establish code patterns
• Enable read operation auto-approve
• Start documenting preferences

Month 1:

• Review learned patterns
• Adjust auto-approve settings
• Export patterns for team

Month 3:

• High confidence autonomous operation
• Fast iteration on familiar tasks
• Agent expertise in your codebase

Measuring Success

Good Signs:

✓ Task completion time decreasing ✓ Fewer approval requests over time ✓ Agent proposing good approaches ✓ Code following your patterns consistently ✓ Confidence scores increasing

Need Improvement:

⚠️ Repeated same questions ⚠️ Not following established patterns ⚠️ Requiring constant corrections ⚠️ Confidence scores not improving

Fix: Review learned patterns, provide more explicit feedback, check consistency in your own code.

Remember

1. Start Simple - Build trust gradually
2. Be Specific - Clear instructions = better results
3. Provide Context - Use @ mentions liberally
4. Review Changes - Always check before committing
5. Give Feedback - Help the agent learn
6. Use Right Mode - Match tool to task
7. Iterate - Build features step by step
8. Trust Gradually - Enable auto-approve as comfortable
9. Learn Together - Agent improves as you work
10. Have Fun - Experiment and explore!

Next Steps

• Read How to Use for practical examples
• Explore Modes for specialized tasks
• Check Self-Learning to understand improvement
• See Examples for real-world patterns

The best practices come from actually using the agent. These guidelines help you start, but you'll develop your own patterns that work for your workflow.