Skip to main content
Ona works out of the box, but it gets better as you configure it. This page walks through best practices in the order most teams adopt them, from writing your first prompt to automating recurring work. Start with the basics and add more as your workflow matures.

​
Write effective prompts

Include a goal, context, constraints, and success criteria. The more precise the prompt, the fewer corrections you need.
A good prompt has four parts:
  1. Goal: What are you trying to change or build?
  2. Context: Which files, docs, errors, or examples matter?
  3. Constraints: What conventions, patterns, or boundaries to follow?
  4. Done when: What should be true when the task is complete?
Example: 
Goal: Add rate limiting to the /api/upload endpoint.
Context: See src/middleware/rateLimit.ts for the existing rate limiter
used on /api/auth. The upload endpoint is in src/routes/upload.ts.
Constraints: Use the same express-rate-limit library and configuration
pattern as the auth endpoint. Limit to 10 requests per minute per user.
Done when: The rate limiter is applied, a 429 response is returned when
the limit is exceeded, and the existing upload tests still pass.
For simple tasks, goal and context are enough. For anything larger, all four parts help Ona stay scoped.

​
Be explicit

Ona performs best with explicit instructions, to the point of over-specification. Clear instructions increase the duration of autonomous work.
Not greatGood
add a new database entity fooadd a database entity foo for the backend which has a name, description and magic value. Users will search for the magic value, but name and desc are only shown. The magic value cannot be changed and is a number from 1 to 100.
add a new endpoint to our backend that allows users to get all of their purchasesTake a look at purchase.go. This file contains the definition for an endpoint that returns a single purchase by ID. Please note how authorization is done and how the tests in purchase_test.go look - these are in line with our best practices. Add a new endpoint (GET /purchases) in the same file to get all of a user’s purchases following the same authorization and testing best practices.
explain the codebaseAnalyze this codebase and explain its general structure, architecture, and key components. What are the most important things a developer should know to get started? Include information about the tech stack, main directories, entry points, and any critical patterns or conventions used.
the sidebar height changes when sessions startUnderstand how:
• we currently keep a stable height for sidebar entries despite font weight changes
• the progress counter pill changes the height of the sidebar item
• we could avoid that height change in line with existing patterns.

Implement that fix.

​
Give Ona context

Ona understands intent, but it cannot read minds. Give it the context it needs.
MethodHow
URLsPoint Ona at documentation, API references, or design specs. It reads web pages directly.
ScreenshotsAttach images by dropping them into the prompt box, using the paperclip button, or pasting from clipboard.
File referencesType @ followed by at least 3 characters to search for files in your environment.
Shell commands!pwd runs a command directly. The output becomes part of the agent’s context.
TODOsSteer the plan at any point: Add a todo item to review and simplify your code

​
Plan before building

For complex changes, separate exploration from implementation. Ask Ona to plan before it codes.
For substantial changes that span multiple components, the explore-plan-build workflow works well:
  1. Explore: Have Ona understand the system. “Examine the authentication flow, including failure modes, security features, database connections, and audit logging. Give me a report of your findings.”
  2. Plan: Design the change. “We need to add audit logs to every login attempt. Ensure this doesn’t impact failure rates and maintains compatibility with all SSO providers. Design a change that achieves this.”
  3. Build: “Implement it.” Ona already has the context and plan.
Ask Ona to write the design to a markdown file, then iterate on it in VS Code. Whenever you update the file, tell Ona to incorporate your changes. This creates a collaborative design loop where you maintain control while using Ona’s capabilities.
For larger changes, ask Ona to reflect on its work: “Review and critique your changes. How can you simplify things?”

​
Teach agents your codebase

Put durable guidance in AGENTS.md and devcontainer.json. Once a prompting pattern works, stop repeating it manually.

​
Write an AGENTS.md

AGENTS.md is a readme for agents. Ona pulls this file into context for every session, making it an ideal place for:
  • Common commands (how to test, rebuild generated code)
  • Key files and parts of the system
  • Code style guide locations
  • Branch naming conventions
Keep it short and concise. You can refer to other files and Ona will read them when necessary. Here’s an example from our own repo:
AGENTS.md
## System Architecture
For architectural understanding, refer to the .llm/ directory which contains
a high-level overview, entity glossary, and tech stack documentation.

## Feature work
- use feature branches from main for pushing work following this naming pattern:
  - [2-3 initials from git config user.name]/[numeric-part-of-issue-ID]-[2-3 word shorthand]
  - should not be more than 24 characters total
IMPORTANT: Always run git config user.name first to get the actual name

## Commit messages
- Follow Conventional Commits: <type>[scope]: <description>
- Types: feat, fix, build, chore, ci, docs, style, refactor, perf, test

## Go Conventions
- Accept interfaces, return concrete types
- Always wrap errors with fmt.Errorf and %w
- Every Ent query must use .Select() to fetch only needed columns

## Code generation
- ALWAYS use leeway scripts to generate code, e.g. `leeway run api/def:generate`
  instead of running `buf generate` directly.
Ona uses Anthropic’s Claude Opus 4.6, and the use of all-caps IMPORTANT and ALWAYS is effective to give extra emphasis to rules. See Teach agents your codebase for the full guide.

​
Tools (Dev Container) and automations

devcontainer.json describes the tools needed to work on a codebase. Developers and agents share this setup. Use Microsoft Dev Container images and align tool versions with the CI pipeline. automations.yaml extends it with tasks and services that automate setup and recurring tasks. Ona Agents can use these automations and add their own, such as serving previews.

​
Extend with integrations

Connect Linear, Slack, and your SCM at the organization level. Use MCP for everything else.
Ona has first-class integrations that connect at the organization level, with no MCP configuration or API keys required. Set them up under Organization Settings > Integrations.
IntegrationWhat it enables
LinearCreate/update issues, search tickets, link code changes. Powers templates like 10x engineer.
SlackNotifications, standup updates, weekly digests, direct interaction from channels.
GitHub / GitLab / BitbucketCode checkout, pull requests, CI log access. Connect under Organization Settings > Integrations.
For tools beyond first-class integrations, Ona supports stdio MCP servers configured in .ona/mcp-config.json. See the configuration guides for Atlassian (Jira), Sentry, and Notion.
User and organization secrets provide secure means to store API keys, as compared to committing them to the repository.

​
Add a “Build with Ona” badge

Add a badge to your repository README to give contributors a one-click link to open the project in an Ona environment. The link uses the app.ona.com/# prefix followed by your repository URL — Ona clones the repo, applies your Dev Container configuration, and starts the environment automatically. Build with Ona 
[![Build with Ona](https://ona.com/build-with-ona.svg)](https://app.ona.com/#https://github.com/your-username/your-repository-name)
Replace your-username/your-repository-name with your GitHub repository path. The link also works with specific branches or subdirectories — append /tree/branch-name to target a branch.

​
Encode expertise in skills

Once a workflow becomes repeatable, turn it into a skill. Skills are organization-wide prompts the agent applies proactively.
Skills settings interface showing available skills Skills encode how your team operates. The agent discovers and applies them proactively, and they can optionally be made available as slash commands. Use them to raise pull requests, review code, and write documentation. Built-in slash commands:
  • /clear resets the session (asks for confirmation)
  • /skills lists available skills (available to org admins)
  • /support-bundle produces a support bundle for when Ona doesn’t work as intended

​
Capture your best reviewers

Capture the review style of your best reviewers by analyzing their last 30 days of PR reviews, identifying patterns, and transforming those insights into a /review-like-[name] skill. See the Encode a reviewer’s style workflow. See Organization-level skills for how to create skills (including example skills we use at Ona), and AGENTS.md skills for repository-specific workflows.

​
Ship code effectively

Be precise about what you want changed. Point to existing patterns instead of specifying every detail.
The most common pitfall is under-specification. Instead of “fix the frontend tests”, be precise: “Fix the flaky frontend tests for the login page where the button selectors aren’t being found correctly.” The key pattern is learning from existing code: “Add a test case to the agent tests that verifies the out-of-token failure mode. Understand the existing test cases and add one that’s highly consistent.”

​
Raising the pull request

Encode your team’s PR standards in a /create-pr skill. Type /create-pr and Ona commits to an appropriately named branch, links to the relevant issue, generates a description, and follows all team conventions. See the Raise a pull request workflow.

​
Adapt your review process

A /code-review skill automates the mechanical parts: gathering diffs, checking conventions, and posting inline comments.
  • Draft PRs as a pressure valve: Push early and often. Let reviewers peek into work-in-progress while agents continue iterating.
  • Tests matter more than implementation details: With AI-generated code, tests define the expected behavior. Prioritize reviewing them.
  • Consistency through context: Maintain coding guidelines as markdown files in your repositories. The agent handles mechanical consistency checks, freeing reviewers for architectural decisions.

​
Treat documentation as code

A /technical-writing skill guides writers so everyone writes in one voice. Make the skill interactive instead of trying to one-shot the result. Encode your team’s critical terminology (e.g. “Dev Container” not “devcontainer”, “environments” not “workspaces”).

​
Automate recurring work

Start from a template. Connect integrations. Let background agents handle the work you do every day.
Ona Automations Automations run on schedules or triggers (new issues, pull requests, webhooks) so work gets done even when you’re not at your desk. Each automation runs in its own isolated environment with full access to your codebase, tools, and integrations. The fastest way to start is from a template:
  • 10x engineer: Daily, picks your top Linear issue, implements it, runs tests, and opens a draft PR
  • Scan recent commits for bugs: Proposes minimal fixes in a draft PR
  • Sentry error triage and fix: Traces errors to source, applies a fix, and opens a PR
  • CVE mitigation and dependency updates: Updates dependencies, runs tests, and opens a PR
  • Draft weekly release notes: Groups the week’s merged PRs by category with summaries
Each automation can run multiple agents concurrently across your projects. Configure concurrency limits and max actions per batch to control scope. Monitor status, success rates, and run history from the Automations dashboard.

​
Ask Ona

“Ask Ona” can become as natural as “Google it” for your team. New developers can use Ona as an onboarding companion instead of consuming senior engineers’ time. Teams can also generate weekly digests and measure agent adoption.

​
Optimize your flow

Run agents in parallel, one environment per task. Let the agent handle 90% of the work; finish the last 10% yourself.

​
Go parallel

Press Cmd+Enter (Ctrl+Enter on non-Mac) to start an agent and stay on the Home page, firing off tasks one after another. Each task gets its own environment: completely isolated, no file conflicts.

​
90% agent, 10% human

Don’t make fine adjustments through the agent. Sometimes opening a text editor and moving that line is faster.
  • Use the agent for the bulk of the changes. Start with precise instructions and encourage questions.
  • Finish and refine in VS Code web. The diff view is useful for initial review.
  • Start an adjustment (e.g. a refactoring) and ask Ona to understand and complete the changes.
90/10 rule illustration showing agent handling 90% of work while human handles 10%

​
Progressive engagement

The complexity of the change determines how deep you go:
  • Simple changes: The session summary is enough to raise a PR directly.
  • Medium changes: VS Code Web for manual edits combined with Ona Agents.
  • Deep work: A desktop IDE, only when establishing a new pattern manually.

​
Preview before you ship

Ona will try to provide a preview when it thinks that’s helpful. You can also ask explicitly: 
Provide a preview for the front end changes you just made.
The generated URL can be shared with colleagues. Previews are useful for mobile development (open the link on your phone) and for before vs after comparisons. Ona providing a preview of frontend changes

​
Commit early, commit often

Git acts as a checkpoint system. Commit any changes that are functional, even if incomplete. Ona can rewrite history or squash commits later. The larger the change, the more often you want Ona to commit. Be explicit: “Commit all your changes, once” or “Keep committing whenever you think is a good time” or “Do not commit or push.”

​
Stay in control

Join the session at any time to course correct. Click Stop or press ESC, then send a corrective message. Use /clear to reset the session while keeping the environment (files, database state, networking). The /clear command interface for resetting a session On mobile: Open app.ona.com on your phone. Agents are autonomous, so mobile works well for checking in, reviewing outcomes, and firing off new tasks.

​
Set guardrails

Agent policies configuration showing MCP, SCM Tools, Conversation Sharing toggles and Command Deny List with aws * blocked
  • Command deny list: Block risky commands across the organization. For example, deny aws * to prevent accidental production operations.
  • Executable deny list: Block binaries by content hash at the kernel level. Cannot be bypassed by renaming or symlinking. Powered by Veto.

​
Common mistakes

  • Overloading prompts with durable rules. Move them into AGENTS.md or a skill.
  • Not telling the agent how to verify its work. Include build, test, and lint commands in AGENTS.md.
  • Skipping planning on complex tasks. For multi-step changes, ask Ona to plan first.
  • Using one environment for multiple tasks. Strive for one environment per task.
  • Micro-adjusting through the agent. Open VS Code and move that line yourself. Follow the 90/10 rule.
  • Automating before the workflow is reliable. Turn it into a skill first, then an automation.
  • Watching the agent step by step. Start a task, work on something else, come back to review. Use parallel tasks.