Best Practices

Habits that emerge from teams who use Barrd daily.

Session discipline

Start every session by loading state

When you begin a conversation with Claude, have it load session state first.

You: Load session state and check for any open tasks

Claude: ↳ Resuming from yesterday: Auth system
Current task: MY-APP-12 (password reset)
2 tasks remaining in plan-auth
Ready to continue.

Save state at natural breakpoints

Don’t save after every message. Save when you’ve completed a task, made a significant decision, or are about to end the session. Think of it like git commits — save at meaningful boundaries.

End sessions explicitly

Before closing a conversation, ask Claude to save session state. This ensures the next session starts with everything it needs. A quick “save state and wrap up” is all it takes.

Task organization

One task per behavior change

A task should represent a single, testable change. “Add authentication” is too broad. “Add login endpoint with JWT” is about right. If you find yourself working on a task for more than a session, it’s probably too big.

The 3-task rule

When you’re about to create a third related task, stop and create a plan first. Plans give Claude a roadmap across sessions — it knows the goal, the approach, and what’s left.

Plan: plan-auth
Goal:  Full authentication with JWT + refresh tokens
Tasks:
✓ MY-APP-5  Registration + personal org
✓ MY-APP-6  Login + JWT tokens
○ MY-APP-7  Password reset flow
○ MY-APP-8  Two-factor auth

Use progress logs

When Claude completes a piece of work, have it log progress with file paths.

Tip

Good progress log: “Added password reset endpoint in src/api/handlers/auth.rs:234, email template in templates/reset.html, migration in 000009_reset_tokens.sql”

Bad progress log: “Fixed the thing”

Plan before you build

Barrd’s workflow enforces a sequence: understand the scope, then plan, then build.

The full workflow

Every code change follows the same pattern:

1. Create a task — before touching any code. The task tracks the entire effort, including planning.
2. Assess scope — is this one task, or three or more related tasks?
3. If 3+ tasks: create a plan first — define the goal, approach, and task breakdown before writing a single line.
4. Write a plan document — link it to the plan and its tasks so every session has context.
5. Implement — work through tasks in order, logging progress with file paths.
6. Save state — at each natural breakpoint, save session state so the next session picks up cleanly.

You: Let's add OAuth support to the API

Claude: This is a multi-part feature. Let me plan
     it before writing any code.

1. Created task MY-APP-20: "Add OAuth support"
2. This will need 4+ tasks, so creating a plan...
3. Created plan: plan-oauth
4. Created implementation document with:
 — Goal, approach, task breakdown
 — Success criteria, risks
5. Created subtasks:
 ○ MY-APP-21  OAuth provider config
 ○ MY-APP-22  Authorization flow
 ○ MY-APP-23  Token exchange + storage
 ○ MY-APP-24  Session integration

Ready to start with MY-APP-21.

Why plan first?

Without a plan, each session starts from scratch. With a plan:

• Every session loads the plan and knows what’s done and what’s next
• Decisions are recorded and referenced
• The implementation document captures the approach
• Progress is tracked with file paths

What makes a good plan?

Plans are implementation blueprints, not wish lists. Before creating one:

• Research first, design second. If the plan touches unfamiliar APIs, crates, or services — verify they exist and do what you think. Create a research task if needed.
• Walk the implementation path. For each task, mentally write the code. What imports? What function signatures? What happens when it fails?
• Name the hard problems. Every plan should have a Risks section with real concerns, not filler.
• Justify estimates. Which tasks are 30 minutes and which are 4 hours? What makes the hard ones hard?

Recording decisions

Capture the “why”, not just the “what”

A decision that says “Use JWT” is useless. A decision that says “Chose JWT with refresh token rotation over session cookies because the API serves both web and MCP clients” is the one that’s useful.

Record when you reject alternatives

The most valuable decisions are the ones where you didn’t do something. “Considered Redis for session storage but stayed with Postgres because we already use it and don’t need the sub-millisecond latency” saves future-you from re-evaluating the same option.

Update decisions when they change

Decisions aren’t permanent. When you outgrow a previous choice, mark it as superseded and create a new decision with the updated rationale. This keeps the history intact while making the current direction clear.

Using documents effectively

Implementation plans before code

For non-trivial features, have Claude create an implementation plan document first. This forces thinking through the approach, edge cases, and dependencies before writing code. Link the document to the plan and its tasks.

Retrospectives after plans

When a plan is completed, create a retrospective document. What went well? What took longer than expected? What would you do differently? Claude reads these in future sessions and gets better at estimating and planning.

Use document types

Tag documents with their type: guide, architecture, decision, implementation, retrospective, test_report. This makes it easy to find the right document later, both for you and for Claude.

Use code intelligence tools

The Barrd MCP server includes AST parsing (tree-sitter) and LSP integration. Faster than reading files or grepping. Use them as the default for code exploration.

AST vs LSP vs Grep

• AST (~100ms) — single-file structure. Every function, struct, import, and call in one request. Use when you’re understanding a file.
• LSP (~300ms) — cross-file intelligence. Go-to-definition, find all references, hover for type info. Use when you’re tracing through a codebase.
• Grep/Read — the fallback. Use when code intelligence tools don’t cover your case (searching for string literals, reading config files, etc.).

You: How does the auth middleware work?

Claude: Let me trace through it.

↳ parse_file_ast("src/api/middleware/auth.rs")
→ 12 functions, 3 structs, 8 imports

↳ lsp(action: "references",
     file: "auth.rs", line: 45)
→ Called from 8 handlers across 4 files

↳ lsp(action: "hover",
     file: "auth.rs", line: 52)
→ fn verify_token(token: &str)
     -> Result<Claims, AuthError>

The auth middleware extracts the JWT from the
Authorization header, verifies it via
verify_token(), and injects Claims into the
request extensions...

When to use which

• Understanding one file? Start with parse_file_ast
• Tracing across files? Use lsp with references or definition
• Finding a symbol by name? Use lsp_workspace_symbols
• Analyzing CSS? Use analyze_file with the css analyzer — one call replaces reading a 4500-line stylesheet

Tell your AI to use them

Add this to your CLAUDE.md (or use the built-in template which includes it):

CLAUDE.md

## Code Intelligence

Use MCP code intelligence tools for code
exploration. AST/LSP are 10-100x faster than
reading files and give more context than grep.

- One file? parse_file_ast
- Multiple files? lsp (references, definition)
- Symbol search? lsp_workspace_symbols

This is your default. Grep/Read is the fallback.

Keeping the model on track

In long sessions, earlier instructions drift out of the model’s active attention as the context window fills up.

What happens in long sessions

As a conversation grows, the model may:

• Stop creating tasks before code changes
• Skip progress logging or omit file paths
• Jump into code without planning
• Fall back to Grep/Read instead of using code intelligence tools
• Forget to save session state at breakpoints

How to handle it

Short reminders are enough:

You: Create a task first before making changes.

You: Use parse_file_ast instead of reading that
   file — it's faster.

You: Remember to plan first. This is 4+ tasks.

You: Log the progress with file paths.

You: Save session state — we're at a good
   stopping point.

Strategies for long sessions

• Break work into sessions. End the session after completing a plan or major task. Start fresh with load_session_state.
• Save state more often. In long sessions, save at every completed task, not just at the end.
• Remind at transitions. When moving from one task to the next, remind the model to check the plan.
• Use the CLAUDE.md template. The built-in template puts the critical rules at the very top so they stay in attention longer.

Note

This is how LLMs work, not a Barrd-specific issue. When in doubt, end the session and start fresh.

Multiple AI assistants

Barrd supports connections from Claude Code, ChatGPT, and any MCP-compatible client. When multiple assistants access the same project:

• They share the same data. Tasks, plans, decisions, and documents are visible to all connected assistants.
• Sessions are per-assistant. Each assistant maintains its own session state, so switching between them doesn’t cause conflicts.
• Decisions are shared. An architectural decision logged by one assistant is referenced by all others.

Tip

You can use different assistants for different strengths. Claude Code for deep implementation sessions, ChatGPT for quick questions and brainstorming — both reading from the same project context.

Team workflows

One project per codebase

Projects in Barrd map to codebases, not teams. If your team works on a single repository, use a single project. If you have a monorepo with distinct services, consider one project per service.

Use task assignment

Assign tasks to team members so Claude knows who’s working on what. When Claude loads session state, it considers the assignee to avoid suggesting work that’s already being handled by someone else.

Share plans, not sessions

Plans and tasks are shared across the team. Sessions are personal. Don’t try to share session state between team members — each person’s Claude instance manages its own context.

CLAUDE.md integration

Your CLAUDE.md file is how you teach the model to follow the Barrd workflow. It’s read at the start of every session and stays in context throughout the conversation.

Use the built-in template

Instead of writing your own from scratch, use the template that ships with the Barrd MCP server:

You: Get the CLAUDE.md template from Barrd and
   set it up for this project

Claude: ↳ get_template({name: "claude_md"})
     ↳ Customizing for your project...

The template puts five rules at the top:

1. Load context at the start of every session
2. Create a task before any code change
3. Log progress with file paths — not vague summaries
4. Save state when work is done
5. Use code intelligence tools — AST/LSP first, Grep/Read as fallback

A companion guide (get_template({name: "template_guide"})) walks through customization.

Works with any MCP client

The template is designed for Claude Code but works with OpenCode and any AI assistant that reads a CLAUDE.md file for project instructions.

Next steps

Dashboard Guide Learn how to use the web dashboard to manage tasks, plans, decisions, and sessions.

MCP Tools Reference Full list of tools available to Claude — sessions, tasks, plans, documents, and more.