Tips & Patterns

Practical advice for getting the most out of Codality.

Start with a simple ticket

Before tackling complex features, test Codality on a small, well-defined ticket. A good first ticket: "Add a health check endpoint that returns the app version." This validates your setup end-to-end.

Use the memory tool

The agent automatically uses the memory tool to look up project context at the start of each session. If it doesn't, add this to your approach prompt: "Always start by querying project overview and recent tickets with the memory tool."

Watch the agent work

The real-time activity feed shows everything the agent does. Watch the first few runs to understand its behavior. This helps you write better prompts and tickets.

Iterate with comments

If the agent goes in the wrong direction, don't wait for it to finish. Send a message while it's running: "Stop working on the UI, focus on the API endpoint first." The agent reads mid-run messages.

Use plans for complex work

Don't try to describe a multi-component feature in one ticket. Write a plan, let the AI help break it down, and extract multiple focused tickets.

Pin file locations

If you know exactly which files need to change, list them in the ticket. This saves the agent exploration time and reduces token usage:

## Files to modify
- internal/handlers/auth.go (add rate limiting middleware)
- internal/handlers/auth_test.go (add tests)

Set up CI early

The CI feedback loop is one of Codality's strongest features. Set up basic CI (build + test) in GitHub Actions early. The agent fixes its own CI failures, which dramatically reduces the back-and-forth.

Customize the approach prompt

The default approach prompt is generic. Tailor it to your project:

## How to approach this
1. Read the README.md for project structure
2. Check the Makefile for build and test commands
3. Use `make test` to run the test suite (not `go test`)
4. Always run `make lint` before committing
5. Follow the error handling patterns in internal/errors/

Use low priority for refactoring

Low priority gives the agent high reasoning effort and encourages thorough, quality-focused work. Assign refactoring chores to low priority so the agent takes time to explore and improve.

One ticket, one concern

The agent works best with focused tickets. "Add user authentication" is better split into:

1. Add auth middleware
2. Add login endpoint
3. Add session management
4. Add auth to existing routes

Each ticket is clear, testable, and reviewable independently.

Review before re-running

If the agent's first attempt isn't right, review what it did before re-running. Add specific feedback as a comment: "The middleware is correct but it should return 401, not 403." Specific feedback produces better results than re-running with the same description.

Back up your database

The SQLite database contains all tickets, plans, agent sessions, and settings. Set up automated backups. The database is the only state that matters — code lives in git.

Monitor token usage

Watch your OpenAI usage dashboard. Complex tickets with large codebases consume more tokens. If costs are a concern:

• Use gpt-4.1 instead of gpt-5.2 for routine work
• Write more specific tickets to reduce exploration
• Pin file locations to reduce unnecessary file reads
• Use gpt-4.1-nano as the fast model (default)