Project: Ledger-Service

nchor.

Implementation: Enable the interactive initialization flow to capture skills, hooks, and memory structure. Set the environment variable to trigger the guided setup.

export CLAUDE_CODE_NEW_INIT=1
claude /init

Architecture Decision: Commit CLAUDE.md to version control. This ensures that every developer and CI environment shares the same baseline context. The file should define tech stack constraints, coding standards, and project-specific conventions.

Example CLAUDE.md Structure:

# Project: Ledger-Service
## Tech Stack
- Runtime: Node.js 20 LTS
- Language: TypeScript 5.4 (Strict Mode)
- Framework: Fastify v4
- ORM: Prisma with PostgreSQL
- Testing: Vitest, Supertest

## Coding Standards
- Use Result<T, E> pattern for error handling; no try/catch blocks in business logic.
- Enforce functional purity in service layer; side effects isolated to adapters.
- No `any` types; use `unknown` with type guards.
- Prefer composition over inheritance for domain models.

## Memory Hooks
- Run `npm run lint:fix` automatically before commit.
- Update Prisma schema before generating migrations.
- Validate all user inputs against Zod schemas.

Rationale: A well-structured CLAUDE.md eliminates the need to re-teach conventions. It reduces the "cold start" cost of sessions and ensures the model adheres to architectural boundaries from the first turn.

2. Session Lifecycle Management

Context windows are finite resources. Effective management requires monitoring usage and compressing history proactively.

Context Monitoring: Use /context to visualize token distribution. This command reveals memory bloat, excessive tool output, or stale history that consumes budget.

claude /context all

Proactive Compaction: Do not wait for performance degradation. Use /compact with focus instructions to summarize the session while preserving critical details.

claude /compact "Focus on the authentication flow refactoring and the new rate-limiting middleware implementation."

Architecture Decision: Schedule compaction every 30–40 turns or before switching sub-tasks. The instruction argument is mandatory; generic compaction loses nuance. Focused compaction ensures the model retains the specific logic required for the next phase of work.

3. Reasoning Optimization

Not all tasks require deep cognitive processing. Applying maximum reasoning depth to simple operations wastes tokens and increases latency.

Effort Control: Use /effort to adjust the reasoning level. Options include low, medium, high, xhigh, and max. The setting applies immediately.

# For documentation or simple refactors
claude /effort low

# For complex architectural changes
claude /effort high

Rationale: Defaulting to max effort is a common inefficiency. Low-effort tasks like comment updates, naming suggestions, or formatting should use minimal reasoning. Reserve high effort for parser design, security analysis, and complex debugging. This trade-off optimizes cost without sacrificing quality where it matters.

4. Safe Exploration and Planning

Refactoring and migration carry risk. The workflow must support experimentation without polluting the working tree or Git history.

Planning Mode: Use /plan to generate a structured approach before implementation. Pass a detailed description to reduce ambiguity.

claude /plan "Refactor the payment processor to support multi-currency settlement without breaking existing USD flows. Analyze dependency graph and propose migration steps."

Rewind Capability: Use /rewind to revert conversation state and code changes to a previous checkpoint. This enables safe testing of alternative approaches.

claude /rewind

Architecture Decision: Treat /rewind as a sandbox mechanism. It allows developers to explore risky changes with a guaranteed rollback path. This reduces the psychological friction of AI-assisted refactoring, encouraging more aggressive optimization.

5. Verification and Shipping

AI-generated code requires rigorous verification. The workflow must provide traceability and security assurance.

Diff Inspection: Use /diff to view an interactive diff of uncommitted changes, including per-turn breakdowns. This identifies exactly which turn introduced a specific modification.

claude /diff

Security Review: Use /security-review to analyze pending changes for vulnerabilities. This command focuses on the delta, checking for injection risks, authentication flaws, and data exposure.

claude /security-review

Rationale: /diff provides accountability, ensuring edits are traceable. /security-review acts as a gatekeeper, catching common vulnerabilities in the specific code being merged. This is more efficient than full-codebase audits and aligns with continuous integration practices.

Pitfall Guide

Pitfall	Explanation	Fix
Context Hoarding	Allowing session history to grow unchecked until the model slows down or forgets details.	Use /compact proactively with focus instructions every 30 turns. Monitor with /context.
Reasoning Overkill	Keeping /effort at max for all tasks, burning tokens on trivial operations.	Set /effort low for docs, formatting, and simple queries. Reserve high/max for complex logic.
The Magic Edit Trap	Committing AI changes without reviewing per-turn diffs, leading to untraceable regressions.	Run /diff after every significant turn. Review changes interactively before staging.
History Pollution	Asking side questions or trivia in the main thread, cluttering context with irrelevant data.	Use /btw for all non-implementation queries. This keeps side questions out of conversation history.
Static Memory	Creating CLAUDE.md once and never updating it, causing the model to drift or miss new conventions.	Run /insights weekly to identify friction points. Update CLAUDE.md based on recurring misunderstandings.
Reinventing the Wheel	Pasting project rules and conventions into chat repeatedly instead of relying on persistent memory.	Run /init on new repos. Commit CLAUDE.md and trust the memory system. Avoid manual context injection.
Security Afterthought	Assuming manual code review catches all vulnerabilities, ignoring AI-assisted delta analysis.	Run /security-review on every feature branch before merge. Focus on injection, auth, and data exposure.

Production Bundle

Action Checklist

• Run /init with CLAUDE_CODE_NEW_INIT=1 on every new repository to seed CLAUDE.md.
• Commit CLAUDE.md to version control to ensure consistent context across the team.
• Configure /effort dynamically: low for routine tasks, high for complex logic.
• Schedule /compact with focus instructions every 30–40 turns to maintain session health.
• Use /btw for all side questions to prevent context pollution.
• Execute /security-review on every feature branch to catch delta-based vulnerabilities.
• Review /diff per-turn to ensure edit traceability and accountability.
• Analyze /insights monthly to prune CLAUDE.md and improve workflow efficiency.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Refactoring Legacy Module	/plan + /rewind + /effort high	High risk requires structured planning and safe rollback capability.	Low (prevents costly rework).
Documentation Update	/effort low + /btw	Simple task; deep reasoning is unnecessary and wasteful.	High savings.
Multi-file Feature Implementation	/compact + /context + /diff	Prevents context overflow and ensures traceability across files.	Medium (maintains velocity).
Quick Syntax or API Check	/btw	Avoids adding trivia to main conversation history.	High savings.
Pre-PR Security Check	/security-review	Automated delta analysis catches injection and auth flaws efficiently.	Low (reduces manual review time).
Workflow Optimization	/insights + /init	Identifies friction points and updates memory to reduce future errors.	Medium (long-term efficiency).

Configuration Template

Use this template to structure a production-grade CLAUDE.md. Adapt sections to your specific stack and conventions.

# Project: [Project Name]
## Tech Stack
- Runtime: [e.g., Node.js 20, Python 3.12]
- Language: [e.g., TypeScript 5.4, Rust 1.75]
- Framework: [e.g., Fastify, Django, Actix]
- Database: [e.g., PostgreSQL, Redis]
- Testing: [e.g., Vitest, Pytest]

## Coding Standards
- [Rule 1: e.g., Use functional error handling]
- [Rule 2: e.g., Enforce strict typing]
- [Rule 3: e.g., Prefer composition over inheritance]
- [Rule 4: e.g., No console.log in production code]

## Architecture Patterns
- [Pattern 1: e.g., Repository pattern for data access]
- [Pattern 2: e.g., Event-driven communication between services]

## Memory Hooks
- [Hook 1: e.g., Run linter before commit]
- [Hook 2: e.g., Generate migration after schema change]

## Project-Specific Context
- [Context 1: e.g., Auth uses JWT with refresh tokens]
- [Context 2: e.g., Payment flow integrates with Stripe]

Quick Start Guide

1. Initialize Repository: Clone your repo and set the environment variable for interactive init.

   export CLAUDE_CODE_NEW_INIT=1
   claude /init
   

2. Configure Memory: Edit the generated CLAUDE.md to include your tech stack, standards, and hooks. Commit the file.

   git add CLAUDE.md
   git commit -m "chore: add Claude Code project memory"
   

3. Set Effort Baseline: Start your session with an appropriate effort level. Use auto or medium as a default, adjusting as needed.

   claude /effort auto
   

4. Begin Development: Use /plan for complex tasks, /btw for side questions, and /compact periodically. Run /security-review before merging.

   claude /plan "Implement user registration endpoint with email verification."
   

5. Review and Ship: Inspect changes with /diff, verify security with /security-review, and commit.

   claude /diff
   claude /security-review