DEV Community: shohei-ai-lab

Stop Losing Context Mid-Session: A Practical Guide to Claude Code's /compact, /clear, and /context Commands

shohei-ai-lab — Sat, 08 Aug 2026 07:38:12 +0000

You're deep into a refactoring session. Claude Code has been reading files, running tests, and building features for an hour. Then suddenly — it asks you a question you already answered 20 minutes ago.

Or worse: it suggests an approach that contradicts the design decision you both agreed on at the start of the session.

The problem isn't that Claude is broken. It's that the context window is full, and important information got silently compressed away.

Every Claude Code user hits this wall eventually. Here's how to manage it deliberately instead of reactively.

Why Context Overflows Faster Than You Think

Claude Code's context window accumulates everything:

Your prompts and Claude's responses
Every file read (hundreds to thousands of tokens each)
Command outputs (test results, build logs, error traces)
Generated code diffs

A single cat of a 200-line file can burn 500+ tokens. Read 10 files, run a test suite, and inspect the error output? You've easily consumed half your context budget before the real work begins.

When the window fills up, Claude Code auto-compacts — summarizing older messages to free space. This is a safety net, not an optimization. The auto-compaction doesn't know which parts of your conversation are critical to preserve.

The 4 Commands You Need

`/context` — Check Your Budget

Before you act, know where you stand.

/context

This renders a colored grid showing how much context is consumed. It also flags optimization suggestions: tools consuming excessive tokens, memory bloat, and capacity warnings.

Add all for a per-item breakdown:

/context all

When to use it: Whenever responses feel slow or lower quality. Think of it as checking fuel level before a long drive.

`/compact` — Summarize and Continue

This is the command you'll use most. It summarizes the conversation so far, freeing context while keeping the session alive.

/compact

The key feature: you can tell it what to preserve.

/compact Keep the auth module design decisions and the list of remaining edge cases

With focus instructions, Claude prioritizes retaining what you specify and aggressively compresses everything else (setup discussions, failed debug attempts, resolved issues).

When to use it:

Transitioning between work phases (design → implementation)
After solving a bug (keep the fix, drop the trial-and-error)
When /context shows 70%+ usage

`/autocompact` — Tune the Safety Net

Controls when auto-compaction triggers.

/autocompact 500k

This sets the threshold to 500k tokens. Use auto to reset to the model-optimized default:

/autocompact auto

The setting persists across sessions.

When to use it:

Large refactoring (raise it — you need more info retained)
Quick single-file fixes (leave at default)
After switching models (different models have different optimal thresholds)

`/clear` — Full Reset

Wipes everything and starts fresh. Unlike /compact, no summary is kept.

/clear

Name the cleared session so you can resume it later:

/clear auth-bugfix

Now you can get back to that conversation anytime with /resume auth-bugfix.

When to use it: Switching to a completely unrelated task where previous context adds zero value.

Practical Patterns

Pattern 1: Phase-Based Compaction

For multi-hour sessions, compact at every phase transition:

Design discussion (30 min)
  └── /compact Keep design conclusions and open questions

Implementation phase 1 (60 min)
  └── /context → /compact if > 70%

Debug session (45 min)
  └── /compact Keep: root cause was X, fix is Y. Drop: failed attempts

Implementation phase 2 (60 min)
  └── final push

The trial-and-error from phase N is rarely useful in phase N+1.

Pattern 2: Task Switching

Task A: Fix login bug
  └── Done → /clear login-fix

Task B: Dashboard redesign
  └── Done → /clear dashboard-v2

Task C: New API endpoint
  └── Working...

Zero context overlap between tasks = use /clear. Name them for future reference.

Pattern 3: Debug Cleanup

Debugging is a context hog. Error traces, stack dumps, hypothesis testing — it all piles up.

Once you find the fix:

/compact Root cause: race condition in auth middleware.
Fix: added mutex lock in handleRequest.
Hypotheses A and B were dead ends — discard.

You keep the conclusion, drop the journey.

Common Mistakes

Mistake 1: Compacting Too Often

Over-compacting loses the "why" behind decisions. Claude starts making suggestions that contradict earlier agreements because the reasoning was compressed away.

Fix: Put persistent design decisions in CLAUDE.md. It's re-read on every compaction — nothing in that file gets lost.

Mistake 2: Using /compact When You Need /clear

Compacting a session about login bugs before starting dashboard work = leftover login context polluting your dashboard session.

Rule of thumb: If zero information from the previous task helps the next one, /clear. If there's any thread connecting them, /compact with focus.

Mistake 3: Never Checking /context

You only discover the problem when auto-compaction silently fires and drops something important.

Fix: Check /context before reading large files or running verbose commands. If you're at 70%+, compact first.

Mistake 4: Compacting Without Focus Instructions

Without guidance, Claude decides what's important on its own. Its priorities may not match yours.

Fix: Always add a one-liner. Focus on: "what's next", "what constraints must survive", "what's the current state". Takes 5 seconds, saves you from repeating yourself later.

Quick Reference

Command	Effect	Session	When
`/context`	Show usage	Continues	Quality feels off
`/context all`	Detailed breakdown	Continues	Need to find what's consuming tokens
`/compact`	Summarize conversation	Continues	Phase transition, 70%+ usage
`/compact [focus]`	Summarize with priority	Continues	Keep specific info alive
`/autocompact [size]`	Set auto-trigger threshold	Persists	Adjust safety net timing
`/clear`	Full reset	New session	Switching to unrelated task
`/clear [name]`	Named reset	New session	Might need to return later

The Takeaway

Context management is the difference between a productive 4-hour session and a frustrating one that degrades after 45 minutes.

The shift is simple: move from reactive (waiting for auto-compaction to save you) to proactive (compacting deliberately, with intent, at natural breakpoints).

Your context window is a resource. Manage it like you manage memory in production code.

For more Claude Code configuration tips, check out our free starter templates:

📦 Claude Code Config Starter Pack (Free) — 3 ready-to-use CLAUDE.md templates
📦 AI Coding Prompt Toolkit (52 prompts) — Structured prompts for common dev workflows
📦 Claude Code Config Pack (20 templates) — Project-type-specific configurations

How to Write a Different CLAUDE.md for Every Project Type — Web, API, CLI, and Library Configs Compared

shohei-ai-lab — Wed, 05 Aug 2026 18:57:58 +0000

You have one CLAUDE.md template. You copy it into every new project. But your CLI tool doesn't need UI component rules, your API server doesn't need routing conventions, and your npm library doesn't care about database access patterns.

A single template can't cover everything. Different project types need different instructions.

After configuring CLAUDE.md across 20+ projects in our AI Autonomous Revenue Project, we developed a clear framework: identify your project type, then prioritize accordingly.

The 3 Things Every CLAUDE.md Needs (Regardless of Type)

Before we diverge by project type, every CLAUDE.md shares this skeleton:

# Stack
- [Language] + [Primary framework/library]
- [Package manager]

# Commands
- Build: [build command]
- Test: [test command]  
- Lint: [lint command]

# Critical Rules (3-5 max)
- [Your most important constraint — with a "why" clause]

This is your universal foundation. Everything below builds on top of it.

Type A: Web Application (Frontend + Backend)

What Makes It Different

Heavy UI component generation
Many structural decisions (routing, state management, auth)
File placement rules are critical

Priority Sections

# Architecture
- Rendering: Server Components by default, "use client" only when needed
- Data fetching: Server Actions for mutations, fetch() for queries
- State: URL params for shareable state, React state for ephemeral UI

# File Placement
- Pages: app/[route]/page.tsx
- Components: src/components/[feature]/
- Server Actions: app/[route]/actions.ts

# UI Rules
- Use shadcn/ui from src/components/ui/
- Styling: Tailwind utility classes only (no CSS modules)
- Responsive: mobile-first (sm:/md:/lg: breakpoints)
- Accessibility: all interactive elements need aria labels

Skip These

Publishing config (no npm publish needed)
SemVer rules (apps typically don't version this way)

Type B: API Server (No Frontend)

What Makes It Different

Endpoint design is the core activity
Request/response type definitions matter most
Error handling must be consistent across all routes

Priority Sections

# API Design
- Response format: { data: T | null, error: { code, message } | null }
- Status codes: 200 (ok), 400 (validation), 401 (auth), 404 (missing), 500 (server)
- Validation: Zod at route entry. Never trust req.body directly
- Auth: Bearer token, validated by middleware before handlers

# Error Handling
- Never expose internals (no stack traces, no SQL in responses)
- All errors logged via structured logger (src/lib/logger.ts)
- Unexpected → 500 with generic message + full internal log

# Database
- All queries through repository pattern (src/repositories/)
- Never raw SQL in route handlers
- Multi-table writes use db.transaction()

Skip These

UI rules, component structure, styling
Detailed routing conventions (framework handles this)

Type C: CLI Tool

What Makes It Different

stdin/stdout/stderr separation matters
Argument parsing and help message consistency
Error messages are user-facing (not developer-facing)

Priority Sections

# CLI Conventions
- Entry point: src/cli.ts
- Argument parsing: use commander/yargs — NOT manual process.argv
- Output: normal → stdout, errors → stderr, progress → stderr
- Exit codes: 0 = success, 1 = user error, 2 = system error

# User-Facing Output
- Errors: explain what's wrong + how to fix it
- No stack traces unless --debug flag is set
- Colors: only when stdout is TTY (check isTTY)
- Progress bars: for operations > 2 seconds

# Configuration
- Config: ~/.config/[tool-name]/config.toml (XDG)
- CLI flags override config file
- Env vars: [TOOL_NAME]_[OPTION] format

Skip These

Database rules
Auth/session management
UI/styling

Type D: Library / Package

What Makes It Different

Public API stability is the #1 concern
Backward compatibility and SemVer are non-negotiable
Documentation (JSDoc/docstrings) is mandatory, not optional

Priority Sections

# Public API Rules
- All exports through src/index.ts (barrel file). No deep imports
- Every public function: JSDoc with @param, @returns, @example
- Breaking changes = major version bump (SemVer strict)
- Internal helpers: underscore prefix or src/internal/

# Compatibility
- Support: Node >= 18 (or your minimum)
- No platform-specific code without fallback
- Dependencies pinned to exact versions

# Testing (stricter than app projects)
- 100% coverage for public API
- Edge cases: null, undefined, empty, large inputs
- Type tests with tsd or expect-type

# Publishing
- CHANGELOG.md updated with every PR
- Pre-publish: full test + build + type check
- Version: use npm version / bump2version / cargo release

Skip These

Deploy procedures (CI/CD handles this)
Framework routing/middleware
Database access

Quick Decision Chart

Does the project have a UI?
  ├─ Yes → Type A (Web App)
  └─ No
       ├─ Does it serve HTTP? → Type B (API Server)
       ├─ Do users run it from terminal? → Type C (CLI Tool)
       └─ Do other projects import it? → Type D (Library)

For hybrid projects (CLI + API, monorepo), apply the right type to each sub-package independently.

Summary Table

Type	Focus On	Safe to Skip
A: Web App	File placement, UI rules, routing	Publishing, SemVer
B: API Server	Response format, error handling, DB	UI, styling
C: CLI Tool	Output targets, exit codes, UX	DB, auth, UI
D: Library	Public API, compatibility, docs	Deploy, DB

Start With a Template

If you want to skip the setup from scratch:

🎁 Claude Code Config Starter Pack (FREE) — 3 templates (Next.js, TypeScript Library, Python FastAPI) covering Types A, B, and D.

🛠️ Claude Code Config Pack — 20 Templates ($5) — All 4 types covered across 20 project configurations including Go, Rust, Flutter, Terraform, Django, and more.

📘 The AI Coding Prompt Toolkit ($5) — 52 prompts for project setup, implementation, testing, and refactoring.

What project types do you use CLAUDE.md with? I'd love to hear about configurations for project types I haven't covered — data pipelines, mobile apps, embedded systems, etc.

5 CLAUDE.md Mistakes That Make Claude Code Ignore Your Rules (and How to Fix Them)

shohei-ai-lab — Tue, 04 Aug 2026 20:34:08 +0000

You wrote a CLAUDE.md. You dropped it in your project root. But Claude Code still uses any, still picks Express when you wanted Next.js, and still ignores your naming conventions.

Sound familiar? You're not alone.

In our previous article, we covered 5 rules for designing system prompts. Today we zoom in on a specific file — CLAUDE.md — and the mistakes that make it ineffective.

After setting up CLAUDE.md configurations across multiple projects in our AI Autonomous Revenue Project, we identified 5 common failure patterns that explain why your CLAUDE.md "doesn't work" — and how to fix each one.

Mistake 1: Writing Aspirations Instead of Instructions

The Problem

# Philosophy
- Clean code is important
- We value readability over cleverness
- Tests should be comprehensive

This reads like a team manifesto, not an instruction set. "Clean code is important" gives Claude Code zero actionable information. What counts as clean? How do you measure it?

Human teammates can infer meaning from cultural context. AI cannot. It interprets text literally.

The Fix

# Coding Rules
- Functions must be under 30 lines. Extract into smaller functions if longer
- Variable names: camelCase, minimum 3 characters (single-letter only for loop counters)
- Every public function needs JSDoc with @param and @returns
- No nested ternary operators — use if/else or early return

Principle: Write rules that can be evaluated as pass/fail. If you can't check whether it was followed, Claude Code can't follow it either.

Corollary: Don't restate what your linter or compiler already enforces. "No any" belongs in tsconfig.json with "strict": true — not in CLAUDE.md. Save your CLAUDE.md context budget for rules that no existing tool can check: architecture boundaries, cross-file intent, and domain-specific constraints.

Mistake 2: Too Much Content (Important Rules Get Buried)

The Problem

Your CLAUDE.md is 200+ lines covering everything: stack details, all commands, every directory explained, 80 coding rules, Git workflow, deploy instructions...

When everything is important, nothing is important. Long configuration files dilute the weight of critical rules.

The Fix

# CRITICAL (always follow these)
- TypeScript strict mode. No `any` type ever
- Server Components by default. "use client" only with explicit directive
- All DB access through src/lib/db/ — never direct Prisma calls in components (RLS is enforced in the db layer)

Each CRITICAL rule benefits from a one-clause "why". The model generalizes better to unseen cases when it understands the reason behind a constraint — not just the constraint itself.

# Stack
- Next.js 14+ (App Router), TypeScript, Tailwind CSS, Prisma

# Commands
- Dev: `pnpm dev` | Build: `pnpm build` | Test: `pnpm test`

# Conventions (see docs/ for full details)
- Named exports only (except page.tsx/layout.tsx)
- Zod schemas in src/schemas/, validated at API boundary

Principle: Use a 3-layer structure:

CRITICAL (3–5 rules at the top — these are non-negotiable. Add a short "why" to each)
Reference info (Stack, Commands — things Claude needs to know)
Details elsewhere (link to docs/ for comprehensive conventions)

Key insight: Tooling owns everything mechanically checkable (tsconfig, ESLint, CI). CLAUDE.md owns cross-file intent and architecture boundaries that no default linter knows about.

Mistake 3: Listing Tech You Don't Actually Use

The Problem

# Stack
- Next.js 14 with App Router
- NextAuth.js v5 for authentication    ← not installed yet
- Prisma + PostgreSQL                   ← actually using Drizzle + SQLite
- Redis for caching                     ← planned but not implemented

Claude Code treats CLAUDE.md as ground truth. If you list libraries that don't exist in your project:

It imports modules that aren't installed
It writes code against APIs that aren't available
It generates structures that contradict your actual setup

This usually happens when you copy a template and forget to customize it.

The Fix

# Stack (ACTUALLY INSTALLED — verify against package.json)
- Next.js 14 with App Router
- Drizzle ORM + SQLite (src/lib/db/schema.ts)
- Tailwind CSS + shadcn/ui

# NOT AVAILABLE (do not use or suggest these)
- No auth library yet (login handled by basic middleware)
- No caching layer (all queries hit DB directly)
- No state management library (use React state + URL params)

Principle: Only list what's actually installed. Explicitly state what's NOT available — this prevents Claude from suggesting it.

Mistake 4: Constraints Without Alternatives

The Problem

# Rules
- Do NOT use any type
- Do NOT add new dependencies
- Do NOT use class components
- Do NOT modify .env files
- Do NOT use default exports
- Do NOT write inline styles

A list of "don'ts" tells Claude what to avoid, but not what to use instead. If any is banned, should it use unknown with type guards? Generics? Explicit type definitions?

The Fix

# Type Safety
- Never use `any`. Instead:
  - External API responses → define with Zod schema, use `z.infer<typeof schema>`
  - Unknown runtime values → `unknown` with type guard functions in src/lib/guards/
  - Generic containers → TypeScript generics with constraints

# Styling
- No inline styles. Instead:
  - Standard styling → Tailwind utility classes
  - Conditional styles → `clsx()` or `cn()` from src/lib/utils
  - Animations → Tailwind's built-in animation utilities

# Dependencies
- No new deps without justification. Use what's already available:
  - Date handling → native Date (no moment/dayjs)
  - HTTP → native fetch (no axios)
  - Validation → existing Zod setup in src/schemas/

Principle: Pair every "don't" with a "do instead". This eliminates ambiguity and gives Claude a clear path forward.

Mistake 5: Writing It Once and Never Updating

The Problem

Your CLAUDE.md was written 3 months ago when the project started. Since then:

Package manager changed from npm → pnpm
Test framework switched from Jest → Vitest
Directory structure was reorganized

Claude Code now runs npm test (fails), writes Jest syntax (wrong), and creates files in directories that no longer exist.

The Fix

Add an update trigger section:

# Meta
Last updated: 2026-08-01
Update this file when:
- [ ] package.json dependencies change
- [ ] Directory structure changes
- [ ] New coding conventions are adopted
- [ ] CI/CD pipeline changes
- [ ] Test framework or build tools change

Principle: CLAUDE.md is a living document. Review it monthly or whenever your project setup changes. Outdated instructions are worse than no instructions.

Quick Checklist: Does Your CLAUDE.md Actually Work?

[ ] Rules are concrete and pass/fail testable (not aspirational)
[ ] CRITICAL section exists with ≤5 rules at the top of the file
[ ] Every tech in Stack section is actually installed (check package.json)
[ ] Every "don't" has a corresponding "do instead"
[ ] File was reviewed within the last 30 days
[ ] Total length is under 100 lines (details are in separate docs)

Resources

If you want to skip the trial-and-error of writing CLAUDE.md from scratch:

🎁 Claude Code Config Starter Pack (FREE) — 3 templates (Next.js, TypeScript Library, Python FastAPI) that follow all the principles above.

🛠️ Claude Code Config Pack — 20 Templates ($5) — Docker-verified configurations for 20 project types including Go, Rust, Flutter, Terraform, and more.

📘 The AI Coding Prompt Toolkit ($5) — 52 structured prompts for project setup, feature implementation, testing, and refactoring.

What CLAUDE.md mistakes have you encountered? Drop a comment below — I'd love to hear about patterns I missed.

5 Essential System Prompt Rules to Stop Your AI Agents from Going Rogue

shohei-ai-lab — Tue, 04 Aug 2026 00:01:40 +0000

We are in the era of autonomous AI agents. Tools like Claude Code, Cline, Cursor, and other agentic coding frameworks are replacing simple Q&A chat interfaces. They can read your workspace, run shell commands, write code, and execute tests.

However, with great power comes great chaos. Every developer using AI agents eventually faces these frustrating moments:

The Loop of Doom: Your agent gets stuck in a compilation-error loop, burning your API credits.
The Overzealous Refactor: The agent rewrites unrelated files, breaking your main branch.
The Hallucination: The agent claims "all tests passed" when they didn't even run.

These issues are not failures of the AI models themselves—they are system prompt failures. Just like human developers, AI agents need clear boundaries, explicit constraints, and rigorous execution rules to perform at their best.

Based on our ongoing experiment, AI Autonomous Revenue Project (where we build and iterate on web products using AI agent workflows with structural verification), we compiled 5 core rules for designing system prompts for AI agents.

Rule 1: Tighten the Role and Grant Specific Authority

Instead of a generic role like "You are a world-class software engineer," define a highly specialized domain expert with distinct behavioral boundaries.

Weak: "You are a senior full-stack developer."
Strong: "You are a strict, no-nonsense senior backend engineer specializing in Next.js, Prisma, and PostgreSQL. Your coding style is minimal, avoiding any unnecessary helper libraries or duplicate imports."

Rule 2: Explicitly Restrict File System Mutability

AI agents have powerful file-writing tools. If left unrestricted, they will modify configuration files, GitHub actions, or package dependencies in unexpected ways. You must establish write-protected zones.

### Write-Protected Files (Read-Only)
- `package.json` and `package-lock.json` (Any dependency update requires explicit human approval)
- `.github/workflows/` (Never modify CI pipelines)
- `tsconfig.json` and linter configurations

Rule 3: Design for Non-Determinism (Stochastic Behavior)

Large Language Models are probabilistic. Never assume the agent's action will succeed on the first try. Your system prompt must define a fallback protocol.

Bad: "Fetch the API data and save it to the database."
Good: "When calling the external API, write error-handling logic with exponential backoff up to 3 retries. If the call still fails, write the complete error payload to logs/error.log and stop the task."

Rule 4: Mandate Automated Evidence Preservation (No Verbal Claims)

Agents are prone to hallucinating task completion. Do not allow them to just say "Everything is working!"

Force the agent to execute real tests and preserve the output files.

Require the agent to output shell execution logs, test suite status codes, and built artifact hashes to a designated folder (e.g., verification/results/).
The system prompt should state: "A task is only considered done when the corresponding test runner output file is generated and matches the expected schema."

Rule 5: Enforce Tool-specific Multi-Line Editing

When editing multiple non-contiguous lines of code, agents often break code files using simple single-line replacements. Instruct them to use multi-replace tools or structural parsers specifically designed for non-adjacent lines. This preserves file integrity and prevents syntax breakage.

DEV Community: shohei-ai-lab

Stop Losing Context Mid-Session: A Practical Guide to Claude Code's /compact, /clear, and /context Commands

Why Context Overflows Faster Than You Think

The 4 Commands You Need

/context — Check Your Budget

/compact — Summarize and Continue

/autocompact — Tune the Safety Net

/clear — Full Reset

Practical Patterns

Pattern 1: Phase-Based Compaction

Pattern 2: Task Switching

Pattern 3: Debug Cleanup

Common Mistakes

Mistake 1: Compacting Too Often

Mistake 2: Using /compact When You Need /clear

Mistake 3: Never Checking /context

Mistake 4: Compacting Without Focus Instructions

Quick Reference

The Takeaway

How to Write a Different CLAUDE.md for Every Project Type — Web, API, CLI, and Library Configs Compared

The 3 Things Every CLAUDE.md Needs (Regardless of Type)

Type A: Web Application (Frontend + Backend)

What Makes It Different

Priority Sections

Skip These

Type B: API Server (No Frontend)

What Makes It Different

Priority Sections

Skip These

Type C: CLI Tool

What Makes It Different

Priority Sections

Skip These

Type D: Library / Package

What Makes It Different

Priority Sections

Skip These

Quick Decision Chart

Summary Table

Start With a Template

5 CLAUDE.md Mistakes That Make Claude Code Ignore Your Rules (and How to Fix Them)

Mistake 1: Writing Aspirations Instead of Instructions

The Problem

The Fix

Mistake 2: Too Much Content (Important Rules Get Buried)

The Problem

The Fix

Mistake 3: Listing Tech You Don't Actually Use

The Problem

The Fix

Mistake 4: Constraints Without Alternatives

The Problem

The Fix

Mistake 5: Writing It Once and Never Updating

The Problem

The Fix

Quick Checklist: Does Your CLAUDE.md Actually Work?

Resources

5 Essential System Prompt Rules to Stop Your AI Agents from Going Rogue

Rule 1: Tighten the Role and Grant Specific Authority

Rule 2: Explicitly Restrict File System Mutability

Rule 3: Design for Non-Determinism (Stochastic Behavior)

Rule 4: Mandate Automated Evidence Preservation (No Verbal Claims)

Rule 5: Enforce Tool-specific Multi-Line Editing

Further Reading & Resources

`/context` — Check Your Budget

`/compact` — Summarize and Continue

`/autocompact` — Tune the Safety Net

`/clear` — Full Reset