OpenHands excels at many development tasks, but knowing when to use it—and when to handle things yourself—helps you get the best results. This guide helps you identify the right tasks for OpenHands and set yourself up for success.
Task Complexity Guidance
Simple Tasks
Ideal for OpenHands — These tasks can often be completed in a single session with minimal guidance.
- Adding a new function or method
- Writing unit tests for existing code
- Fixing simple bugs with clear error messages
- Code formatting and style fixes
- Adding documentation or comments
- Simple refactoring (rename, extract method)
- Configuration changes
Example prompt:
Add a calculateDiscount() function to src/utils/pricing.js that takes
a price and discount percentage, returns the discounted price.
Add unit tests.
Medium Complexity Tasks
Good for OpenHands — These tasks may need more context and possibly some iteration.
- Implementing a new API endpoint
- Adding a feature to an existing module
- Debugging issues that span multiple files
- Migrating code to a new pattern
- Writing integration tests
- Performance optimization with clear metrics
- Setting up CI/CD workflows
Example prompt:
Add a user profile endpoint to our API:
- GET /api/users/:id/profile
- Return user data with their recent activity
- Follow patterns in existing controllers
- Add integration tests
- Handle not-found and unauthorized cases
Complex Tasks
May require iteration — These benefit from breaking down into smaller pieces.
- Large refactoring across many files
- Architectural changes
- Implementing complex business logic
- Multi-service integrations
- Performance optimization without clear cause
- Security audits
- Framework or major dependency upgrades
Recommended approach:
Break large tasks into phases:
Phase 1: "Analyze the current authentication system and document
all touch points that need to change for OAuth2 migration."
Phase 2: "Implement the OAuth2 provider configuration and basic
token flow, keeping existing auth working in parallel."
Phase 3: "Migrate the user login flow to use OAuth2, maintaining
backwards compatibility."
Best Use Cases
Ideal Scenarios
OpenHands is most effective when:
| Scenario | Why It Works |
|---|
| Clear requirements | OpenHands can work independently |
| Well-defined scope | Less ambiguity, fewer iterations |
| Existing patterns to follow | Consistency with codebase |
| Good test coverage | Easy to verify changes |
| Isolated changes | Lower risk of side effects |
- Bug fixes with reproduction steps: Clear problem, measurable solution
- Test additions: Existing code provides the specification
- Documentation: Code is the source of truth
- Boilerplate generation: Follows established patterns
- Code review and analysis: Read-only, analytical tasks
Good Fit Scenarios
OpenHands works well with some guidance for:
- Feature implementation: When requirements are documented
- Refactoring: When goals and constraints are clear
- Debugging: When you can provide logs and context
- Code modernization: When patterns are established
- API development: When specs exist
Tips for these scenarios:
- Provide clear acceptance criteria
- Point to examples of similar work in the codebase
- Specify constraints and non-goals
- Be ready to iterate and clarify
Poor Fit Scenarios
Consider alternatives when:
| Scenario | Challenge | Alternative |
|---|
| Vague requirements | Unclear what “done” means | Define requirements first |
| Exploratory work | Need human creativity/intuition | Brainstorm first, then implement |
| Highly sensitive code | Risk tolerance is zero | Human review essential |
| Organizational knowledge | Needs tribal knowledge | Pair with domain expert |
| Visual design | Subjective aesthetic judgments | Use design tools |
- “Make it look better” (subjective)
- “Figure out what’s wrong” (too vague)
- “Rewrite everything” (too large)
- “Do what makes sense” (unclear requirements)
- Changes to production infrastructure without review
Limitations
Current Limitations
Be aware of these constraints:
- Long-running processes: Sessions have time limits
- Interactive debugging: Can’t set breakpoints interactively
- Visual verification: Can’t see rendered UI easily
- External system access: May need credentials configured
- Large codebase analysis: Memory and time constraints
Technical Constraints
| Constraint | Impact | Workaround |
|---|
| Session duration | Very long tasks may timeout | Break into smaller tasks |
| Context window | Can’t see entire large codebase at once | Focus on relevant files |
| No persistent state | Previous sessions not remembered | Use AGENTS.md for context |
| Network access | Some external services may be blocked | Use local resources when possible |
Scope Boundaries
OpenHands works within your codebase but has boundaries:
Can do:
- Read and write files in the repository
- Run tests and commands
- Access configured services and APIs
- Browse documentation and reference material
Cannot do:
- Access your local environment outside the sandbox
- Make decisions requiring business context it doesn’t have
- Replace human judgment for critical decisions
- Guarantee production-safe changes without review
Pre-Task Checklist
Prerequisites
Before starting a task, ensure:
Environment Setup
Prepare your repository:
## AGENTS.md Checklist
- [ ] Build commands documented
- [ ] Test commands documented
- [ ] Code style guidelines noted
- [ ] Architecture overview included
- [ ] Common patterns described
Repository Preparation
Optimize for success:
- Clean state: Commit or stash uncommitted changes
- Working build: Ensure the project builds
- Passing tests: Start from a green state
- Updated dependencies: Resolve any dependency issues
- Clear documentation: Update AGENTS.md if needed
Post-Task Review
Quality Checks
After OpenHands completes a task:
Validation Steps
- Run tests:
npm test, pytest, etc.
- Check linting: Ensure style compliance
- Build the project: Verify it still compiles
- Manual testing: Test the feature yourself
- Edge cases: Try unusual inputs
Learning from Results
After each significant task:
What went well?
- Note effective prompt patterns
- Document successful approaches
- Update AGENTS.md with learnings
What could improve?
- Identify unclear instructions
- Note missing context
- Plan better for next time
Update your repository:
## Things OpenHands Should Know (add to AGENTS.md)
- When adding API endpoints, always add to routes/index.js
- Our date format is ISO 8601 everywhere
- All database queries go through the repository pattern
Decision Framework
Use this framework to decide if a task is right for OpenHands:
Is the task well-defined?
├── No → Define it better first
└── Yes → Continue
Do you have clear success criteria?
├── No → Define acceptance criteria
└── Yes → Continue
Is the scope manageable (< 100 LOC)?
├── No → Break into smaller tasks
└── Yes → Continue
Do examples exist in the codebase?
├── No → Provide examples or patterns
└── Yes → Continue
Can you verify the result?
├── No → Add tests or verification steps
└── Yes → ✅ Good candidate for OpenHands
When in doubt, start small. A focused task that succeeds builds confidence for larger tasks. You can always iterate and expand scope based on results.
