When to Use OpenHands

​

Task Complexity Guidance

​

Simple Tasks

• 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

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

• 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

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

• 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

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

• 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

• 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

1. Provide clear acceptance criteria
2. Point to examples of similar work in the codebase
3. Specify constraints and non-goals
4. Be ready to iterate and clarify

​

Poor Fit Scenarios

• “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

• 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

​

Scope Boundaries

• Read and write files in the repository
• Run tests and commands
• Access configured services and APIs
• Browse documentation and reference material

• 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

• Clear description of what you want
• Expected outcome is defined
• Relevant files are identified
• Dependencies are available
• Tests can be run

​

Environment Setup

## AGENTS.md Checklist

- [ ] Build commands documented
- [ ] Test commands documented  
- [ ] Code style guidelines noted
- [ ] Architecture overview included
- [ ] Common patterns described

​

Repository Preparation

1. Clean state: Commit or stash uncommitted changes
2. Working build: Ensure the project builds
3. Passing tests: Start from a green state
4. Updated dependencies: Resolve any dependency issues
5. Clear documentation: Update AGENTS.md if needed

​

Post-Task Review

​

Quality Checks

• Review all changed files
• Understand each change made
• Check for unintended modifications
• Verify code style consistency
• Look for hardcoded values or credentials

​

Validation Steps

1. Run tests: npm test, pytest, etc.
2. Check linting: Ensure style compliance
3. Build the project: Verify it still compiles
4. Manual testing: Test the feature yourself
5. Edge cases: Try unusual inputs

​

Learning from Results

• Note effective prompt patterns
• Document successful approaches
• Update AGENTS.md with learnings

• Identify unclear instructions
• Note missing context
• Plan better for next time

## 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

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

• Clearly Specified Tasks: Generally, if the task has a very clear success criterion, OpenHands will do better. It is especially useful if you can define it in a way that can be verified programmatically, like making sure that all of the tests pass or test coverage gets above a certain value using a particular program. But even when you don’t have something like that, you can just provide a checklist of things that need to be done.
• Highly Repetitive Tasks: These are tasks that need to be done over and over again, but nobody really wants to do them. Some good examples include code review, improving test coverage, upgrading dependency libraries. In addition to having clear success criteria, you can create “skills” that clearly describe your policies about how to perform these tasks, and improve the skills over time.
• Helping Answer Questions: OpenHands agents are generally pretty good at answering questions about code bases, so you can feel free to ask them when you don’t understand how something works. They can explore the code base and understand it deeply before providing an answer.
• Checking the Correctness of Library/Backend Code: when agents work, they can run code, and they are particularly good at checking whether libraries or backend code works well.
• Reading Logs and Understanding Errors: Agents can read blogs from GitHub or monitoring software and understand what is going wrong with your service in a live production setting. They’re actually quite good at filtering through large amounts of data, especially if pushed in the correct direction.

• Quality Assurance of Frontend Apps: Agents can spin up a website and check whether it works by clicking through the buttons. But they are a little bit less good at visual understanding of frontends at the moment and can sometimes make mistakes if they don’t understand the workflow very well.
• Implementing Code they Cannot Test Live: If agents are not able to actually run and test the app, such as connecting to a live service that they do not have access to, often they will fail at performing tasks all the way to the end, unless they get some encouragement.