Best practices for using Ona environments, agents, and guardrails effectively in your development workflow.
devcontainer.json
describes the tools needed to work on a particular codebase. Developers and agents share this setup. It’s helpful to use Microsoft dev container images and align tool versions with the CI pipeline (e.g. use an exact version of Java).
Ona’s automations.yaml
extends it with tasks and services that automate set up and reoccurring tasks. Our own monorepo setup contains automations for running the backend, frontend and rebuilding API code. Ona Agents can use these automations, and add their own e.g. for serving previews.
.ona/mcp-config.json
. The format is aligned with other common MCP server configuration files, such as Claude Desktop or Cursor. We use MCP servers to enable richer GitHub interaction, and to connect to Linear.
Note: some organizations might not allow the use of MCP, and can disable MCP support in the settings.
LINEAR_API_KEY
environment variable configured as secret.
aws *
in the deny list. This way, should an engineer accidentally sign into production, we are certain no unforeseen database deletions occur.
/clear
which resets the conversation (asks for confirmation)/commands
which is available to org admins and/support-bundle
which produces a support bundle for when Ona doesn’t work as intended./pr
to raise pull requests
/weekly-digest
to get a summary of changes in the last week
/fix-ci-build
for fixing CI builds on branches
/create-runbook
to write new runbooks consistently
/changelog-ona-swe-agent
to produce user-facing changelog and Slack announcement for Ona SWE agent releases
/catch-up
to catch the agent up to changes in an environment
/docs-writer
command that guides someone writing documentation through the produce so that we all write in one voice.
Our own documentation is written using Ona using a prompt similar to the one below.
The docs writer prompt contains instructions for an interactive conversation, rather than trying to one-shot the result. Next to instructions like “Write like Strunk and White’s Elements of Style” it contains a workflow section encouraging the agent to ask clarifying questions.
/pr
command. When an engineer is satisfied with their changes, they simply type /pr
and Ona walks through the entire process:
/review-like-mads
commandAdd a todo item to review and simplify your code
Remove the next todo item
!pwd
runs the command directly instead of instructing the agent.
The command and output become part of the agent’s context. This is a powerful tool to explicitly give context to the agent, e.g. a particular file listing or test failures. It also ensures the agent and you are on the same page.
/clear
for a clean slate/clear
is helpful. It resets the conversation with the agent, but keeps the environment as is. This is an escape hatch, not a recommended way of working.
Not Great | Good |
---|---|
add a new database entity foo | add 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 purchases | Take 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 practises. 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 codebase | Analyze 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 conversations start | Understand 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. |