Best Practices

Write better objectives, organize initiatives clearly, and keep your context files useful. These patterns help agents succeed on the first pass.

Writing effective objectives

Objectives

Objectives describe outcomes, not tasks. Write what should be true when the work is done, not a list of steps to get there.

Good

"Add OAuth login with Google and GitHub" — clear outcome, testable
"Users can export reports as PDF" — describes the capability, not the implementation
"API rate limiting prevents abuse" — outcome-focused, leaves implementation to the agent
"Search returns results in under 200ms for 95th percentile" — specific, measurable acceptance criterion

Avoid

"Install NextAuth and configure providers" — this is a step, not an outcome
"Refactor the auth module" — refactoring toward what? No clear done state
"Fix bugs" — which bugs? How will we know they're fixed?
"Improve performance" — by how much? Where? This needs specifics

Acceptance criteria that work

Objectives

Acceptance criteria are the checklist the agent uses to verify the work is complete. They should be specific enough to test, general enough to allow implementation flexibility.

Write each criterion as a statement that can be checked true or false. Avoid vague terms like "improved" or "better" — specify what improved means. Include edge cases that matter. Skip edge cases that don't. The goal is a clear done state, not exhaustive specification.

Good

Users can sign in with Google OAuth
Sessions persist across browser restarts
Invalid credentials show an error message (not a blank screen)
Rate limit returns 429 with Retry-After header

Avoid

Code is clean and well-organized — subjective, not testable
Performance is acceptable — what's acceptable?
All edge cases handled — which edge cases?
Documentation updated — which docs? Updated how?

Right-sizing objective scope

Objectives

An objective should be small enough to complete in one agent session, large enough to deliver meaningful value. If it takes multiple PRs, it's too big. If it's trivial, it might not need tracking.

Scope signals

Signal	What it means
Touches 1-5 files	Good scope — focused change
Touches 10+ files	Consider splitting into multiple objectives
Requires multiple PRs	Definitely too big — split it
Single function change	Might be too small for an objective — just do it
Unclear where to start	Needs breakdown or clarification before scheduling

Naming initiatives clearly

Initiatives

Initiative names should communicate what the team is trying to accomplish, not when or how. They're for humans scanning a board, not for agents.

Good

OAuth Integration — clear capability being added
Performance Optimization — clear area of focus
SOC 2 Compliance — clear outcome
Mobile App v2 — versioned release milestone

Avoid

Sprint 47 — means nothing to anyone outside the team
Q3 Work — temporal, not outcome-focused
Misc Improvements — too vague to be useful
Tech Debt — every project has this; be specific about which debt

Avoiding initiative sprawl

Initiatives

More initiatives doesn't mean more progress. Too many active initiatives dilutes focus and makes the board harder to read.

Before creating a new initiative, ask: does this represent a distinct outcome, or is it part of something already in flight? Group related objectives under one initiative rather than creating one initiative per objective. Mark initiatives as released when they're done — they'll archive and the board stays clean.

When to create vs. extend

Scenario	Action
New feature area not covered by existing initiatives	Create new initiative
Follow-up work on a shipped feature	Add to existing initiative (or create v2)
Bug fixes for a feature	Add to the feature's initiative, not a separate "bugs" initiative
Cross-cutting infrastructure work	Create initiative if it's substantial; otherwise add to affected initiatives
Single objective with no siblings	Consider if it needs an initiative at all — backlog is fine

Context file hygiene

Context Files

Context files encode institutional knowledge. Keep them current, specific, and focused. Stale context is worse than no context.

Review context files when you reject an objective for reasons that should have been in context. If the agent made a mistake because it didn't know something, that's a signal to add or update a context file. Don't let context files become graveyards of outdated decisions.

Good

Update when architecture decisions change
Add when an agent makes a mistake due to missing knowledge
Remove deprecated guidance that no longer applies
Keep files focused — one topic per file, not a mega-document

Avoid

Copy-paste entire README files — that's redundant with the repo
Include step-by-step task instructions — that's an objective
Let files grow unbounded — split when they get long
Assume agents read everything — they scan file names first

Context files vs. CLAUDE.md

Context Files

CLAUDE.md lives in the repo and handles mechanical setup. Context files live in Planwright and handle strategic knowledge.

Use CLAUDE.md for

Build commands and local dev setup
Linting and formatting rules
Commit message conventions
Test commands and coverage requirements
Repo-specific tooling instructions

Use context files for

Architecture decisions and tradeoffs
Deprecated patterns to avoid
Service boundaries and ownership
External API quirks and workarounds
Team conventions not enforced by tooling

← Tracker Integrations How-To Guides →