Best Practices

Session discipline

Start every session by loading state

The most important habit. When you begin a conversation with Claude, have it load session state first. This gives it full context on what happened last time — tasks in progress, decisions made, files changed.

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. This creates an audit trail that's invaluable when debugging or onboarding team members.

Plan before you build

The most common mistake is jumping straight into code. Barrd's workflow enforces a sequence: understand the scope, then plan, then build. This applies whether you're working with Claude Code, OpenCode, or any MCP-connected assistant.

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. Claude doesn't know the overall goal, doesn't know what's been decided, and may make conflicting choices. With a plan:

• Every session loads the plan and knows exactly what's done and what's next
• Decisions are recorded and referenced — no relitigating past choices
• The implementation document captures the approach, so a new session (or a different team member's session) can pick up without re-explaining
• Progress is tracked with file paths, so you can trace what changed and where

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" prevents the same debate from happening in three months.

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. These are dramatically faster and more accurate than reading files or grepping for strings. Use them as your 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…

Compare that to the alternative: 5+ Read calls to open files, multiple Grep calls to find usages, and still missing type information. Code intelligence gives you the answer in 2–3 tool calls.

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):

## 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

AI models don't have perfect memory within a conversation. In long sessions — especially with Claude Code or OpenCode — earlier instructions can drift out of the model's active attention as the context window fills up. This is normal behavior, not a bug.

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

This is especially common after the conversation has been going for a while and the CLAUDE.md instructions have been pushed far back in the context.

How to handle it

Gentle reminders work. You don't need to re-explain the entire workflow. A short nudge is 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 — the model reloads your CLAUDE.md and starts with full attention on the instructions.
• Save state more often. In long sessions, save state at every completed task, not just at the end. This gives you clean restart points.
• Remind at transitions. When moving from one task to the next, remind the model to check the plan and create/update the task.
• Use the CLAUDE.md template. The built-in template puts the most important rules (create tasks, log progress, use code intelligence) at the very top as "Non-Negotiable Rules" — this helps them stay in attention longer.

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. A task created by Claude Code is visible to ChatGPT, and vice versa.
• 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.

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 includes five non-negotiable rules at the top — placed there deliberately so they stay in the model's attention as long as possible:

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

It also includes the planning workflow, code intelligence examples, batch operations, and placeholders for your project's tech stack and patterns. A companion guide (get_template({name: "template_guide"})) walks through customization step by step.

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