Ongoing Operations

• What this covers: Everything you need to manage day-to-day while working with Claude Code. 

• When to use: Reference this throughout every project.

• Reference document -- no single output. Use throughout every project.

Context Management (the most important operational skill)

Context is the #1 thing that causes Claude to degrade. If you learn one thing from this document, learn this section. If you configured the statusline in setup, your context percentage is always visible. If the bar is yellow, start planning a compact. If it is red, stop and clear immediately.

The rules:

• /context shows your current usage. Check it regularly.

• Stay below 60%. At 60%, you MUST compact or clear.

• Auto-compaction triggers at ~85% and will interrupt your work unexpectedly.

• /clear resets the conversation but keeps CLAUDE.md loaded. Use between phases.

• /compact summarises the conversation to free space. Always add a focus instruction:/compact preserving Phase 3 progress, test results for user authentication, and the current database schema

• Between phases, always /clear. Start each phase clean.

• If Claude starts repeating itself, forgetting instructions, or making mistakes it did not make before — your context is too full. Clear immediately.

• The Notification hook (\context-warning.sh\) will automatically warn you when context approaches the ceiling, but do not rely on it exclusively — check /context yourself before and after every phase.

Signs your context is too full:

• Claude forgets decisions made earlier in the conversation

• Claude suggests approaches you already rejected

• Claude starts hallucinating file names or APIs

• Responses become slower

• Code quality drops noticeably

Token efficiency with Serena:

When Claude needs to understand existing code, prefer Serena's semantic navigation (find references, go to definition, type hierarchy) over reading entire files. A Serena symbol lookup returns precisely the information needed. Reading a 500-line file to find one function signature wastes context that could be used for actual work.

Cost Management

Claude Code costs money. Be intentional.

Check your spending:

/cost

This shows token usage for the current session.

Cost reduction strategies:

• Use opusplan (Opus for thinking, Sonnet for code) — this is cheaper than pure Opus

• Keep context clean — large contexts mean more tokens per response

• Use subagents for focused tasks — they have smaller contexts

• Clear between phases — do not carry unnecessary history

• Be specific in prompts — vague prompts cause Claude to explore more (and spend more)

• Agent Teams use ~5x more tokens than single sessions — only use when genuinely needed

Set a budget: Decide on a weekly/monthly budget per team member and track it. There is no built-in spending cap, so this requires discipline.

Cost tracking template:

Create /docs/cost-log.md at project start with this structure:

# Cost Log | Date | Phase | Session Type | Token Cost | Notes |
|------|-------|-------------|-----------|-------|
| 2026-02-20 | Phase 1 | Solo | $2.40 | Initial DB setup |
| 2026-02-20 | Phase 2 | Agent Team (3) | $11.20 | API + Frontend + Tests |

Update this after every session by running /cost before closing Claude Code. This makes budget conversations concrete rather than guesswork.

Security Operations

Every day:

• Never commit .env files (the .claude/rules/security.md rule helps, but verify)

• Review every shell command Claude proposes before approving

• Never approve commands you do not understand — ask Claude to explain

Every PR:

• Run the security review from Test and VerifyStep 2

• Check for hardcoded secrets in the diff

• Verify auth/authz is correct

Project-level settings (already configured in kickoff):

// .claude/settings.json
{ "permissions": { "deny": [ "Read(.env*)", "Read(secrets.*)", "Read(credentials.*)", "Write(.env*)" ] }
}

For enterprise teams: Ask your IT admin about managed settings at the system level, and the disableBypassPermissionsMode setting.

Personal secrets: Use .claude/settings.local.json for per-developer config (auto-gitignored):

{ "env": { "DATABASE_URL": "your-local-db-url" }
}

Beads: Task Management

Beads keeps track of multi-step work across sessions. Use it for everything that takes more than one Claude Code session to complete.

Common commands:

bd ready           # Load the current active issue context into the session
bd status          # See all issues and their status
bd create          # Create a new issue
bd list            # List issues with filters
bd show [id]       # Show details of an issue
bd complete [id]   # Mark an issue as done
bd comment [id]    # Add notes to an issue

When to create Beads issues:

• Each build phase from the implementation plan

• Any bug discovered during testing

• Any technical debt or improvement identified

• Any decision that needs follow-up

• Any task that spans multiple sessions

• If Beads is unavailable or broken: See the fallback procedure in Troubleshooting under "Beads is unavailable, broken, or returning errors." A manual /docs/tasks.md tracker can substitute until Beads is restored.

Using Custom Slash Commands

You can create project-specific commands. These live in .claude/commands/.

To use a command:

/project:create-adr # runs the create-adr command we made during kickoff

To create new commands: Create a markdown file in .claude/commands/[name].md:

---
description: What this command does
allowed-tools: Write, Read, Bash
---
Instructions for Claude when this command is invoked.

Useful custom commands to add:

• /project:run-tests — runs your specific test suite

• /project:new-feature — scaffolds a new feature branch and Beads issue

• /project:deploy — runs the deployment sequence

Superpowers slash commands: Superpowers adds several commands that are available in every project:

• /superpowers:brainstorm - Interactive design refinement (useful for ad-hoc features)

• /superpowers:write-plan - Create an implementation plan for a specific task

• /superpowers:execute-plan - Execute a plan in batches

These complement our formal workflow. Use them for work that does not go through the full Idea Pack to Implementation Plan cycle -- bug fixes, small features, refactors, and exploratory work.

Using Custom Agents

You can define custom subagents that specialise in specific tasks. These live in .claude/agents/.

Create an agent: Create a markdown file in .claude/agents/[name].md:

---
description: Database migration specialist
model: sonnet
allowed-tools: Write, Read, Bash
---
You are a database migration specialist. You: - Only work on migration files in /migrations/
- Follow our migration naming convention: YYYYMMDDHHMMSS_description.sql
- Always create both up and down migrations
- Test migrations before completing

Use an agent:

Use the database agent to create a migration for adding the 'status' column to the projects table.

Updating Your Tools

Periodically update your toolchain:

# Update Claude Code
npm update -g @anthropic-ai/claude-code # Update Beads
brew upgrade beads
# or: npm update -g @beads/bd # Check Claude Code health after updates
claude /doctor

After major Claude Code updates, re-run Verify Your Setup to confirm everything still works.

Also check whether the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS flag in .claude/settings.json is still required. This is an experimental feature that may be promoted to stable (no flag needed) or changed between releases. Check the Claude Code release notes after each update.

Environment Management

Development: Your local machine. Use .claude/settings.local.json for local config.

Staging: A shared environment that mirrors production. Deploy here first for team testing.

Production: The live environment. Never deploy directly — always go through staging first.

Pattern:

1. Build and test locally

2. Create PR → CI/CD runs tests

3. Merge to main → auto-deploy to staging

4. Verify on staging → manual deploy to production

5. Verify on production

When to create ADRs

Create a new ADR whenever:

• You choose a new library or framework

• You change the database schema significantly

• You decide on an API structure

• You change the deployment approach

• You make any decision that a team member would ask "why?" about later

Use the custom command:

/project:create-adr

Or tell Claude directly:

Create a new ADR in /docs/adr/ about our decision to [describe the decision].