From 7a6d369512a80fb161a6cef18f4707448d707edc Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 19 Jan 2026 09:06:39 +0100 Subject: [PATCH] docs: add subscription plans section & semantic anchors - Add "Subscription Plans & Limits" section (line 1750) - Concepts: message windows, hybrid counting, weekly caps - Tier-specific strategies (no volatile numbers) - Links to official pricing page - Add Semantic Anchors section (2.7) with anchor catalog - Fix drifted line numbers in reference.yaml - Add 6 new slash commands (catchup, security, refactor, etc.) Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 20 ++++ README.md | 4 +- guide/cheatsheet.md | 4 +- guide/ultimate-guide.md | 203 +++++++++++++++++++++++++++++++- machine-readable/reference.yaml | 17 +-- 5 files changed, 232 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e2cb0b9..45676f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Semantic Anchors** — New concept integrated for better LLM prompting + - Section 2.7 "Semantic Anchors" in `guide/ultimate-guide.md` (~93 lines) + - Explains how precise vocabulary helps LLMs activate correct patterns + - Common anchors table (vague → precise) with explanations + - Integration examples with CLAUDE.md and XML tags + - `examples/semantic-anchors/anchor-catalog.md` (NEW, ~320 lines) + - Comprehensive catalog organized by domain (Testing, Architecture, Design, etc.) + - Before/after examples showing prompt improvement + - CLAUDE.md template with anchors integrated + - Source attribution: Alexandre Soyer, [github.com/LLM-Coding/Semantic-Anchors](https://github.com/LLM-Coding/Semantic-Anchors) (Apache-2.0) + - Section numbering fixed: 2.6 Data Flow → 2.8, 2.7 Under the Hood → 2.9 + +- **Subscription Plans & Limits** — New section documenting subscription concepts + - Section "#### Subscription Plans & Limits" in `guide/ultimate-guide.md` (~42 lines) + - Explains message windows, hybrid counting, weekly caps, model weighting + - Tier-specific strategies (limited → unlimited quota) + - Links to official pricing page (concepts only, no volatile numbers) + - Updated `machine-readable/reference.yaml` with `subscription_limits: 1750` + - Fixed drifted line numbers in reference.yaml (commands_table, shortcuts_table, etc.) + - **6 new slash commands** (Sprint 1 + Sprint 2 implementation) - `examples/commands/catchup.md` - Restore context after `/clear` (137 lines) - Git history analysis (last 10 commits, recent diffs) diff --git a/README.md b/README.md index 024fb88..175a7be 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

Stars - Lines + Lines Templates Quiz

@@ -432,7 +432,7 @@ Weak Areas (< 75%): ``` claude-code-ultimate-guide/ ├── guide/ # 📖 Core documentation -│ ├── ultimate-guide.md # Complete reference (~10200 lines) +│ ├── ultimate-guide.md # Complete reference (~10300 lines) │ ├── cheatsheet.md # 1-page printable reference │ ├── architecture.md # How Claude Code works internally │ ├── adoption-approaches.md # Team implementation strategies diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md index 0babf71..41ed017 100644 --- a/guide/cheatsheet.md +++ b/guide/cheatsheet.md @@ -6,7 +6,7 @@ **Written with**: Claude (Anthropic) -**Version**: 3.8.2 | **Last Updated**: January 2026 +**Version**: 3.9.0 | **Last Updated**: January 2026 --- @@ -397,4 +397,4 @@ where.exe claude; claude doctor; claude mcp list **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude -*Last updated: January 2026 | Version 3.8.2* +*Last updated: January 2026 | Version 3.9.0* diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 061270b..81267de 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -10,7 +10,7 @@ **Last updated**: January 2026 -**Version**: 3.8.2 +**Version**: 3.9.0 --- @@ -1747,6 +1747,48 @@ Monthly cost estimate: $50-$200 for 5-10 developers | >$5/day for hobby project | Over-using or inefficient queries | Review query specificity | | Haiku failing simple tasks | Using wrong model tier | Use Sonnet for anything non-trivial | +#### Subscription Plans & Limits + +> **Note**: Anthropic's plans evolve frequently. Always verify current pricing and limits at [claude.com/pricing](https://claude.com/pricing). + +**How Subscription Limits Work** + +Unlike API usage (pay-per-token), subscriptions use a different model: + +| Concept | Description | +|---------|-------------| +| **Message windows** | Limits reset periodically (e.g., every few hours), not daily | +| **Hybrid counting** | Advertised as "messages" but actual capacity varies by message length, attachments, and context size | +| **Weekly caps** | Higher tiers may have weekly limits to prevent continuous 24/7 usage | +| **Model weighting** | Opus consumes quota faster than Sonnet; Haiku is lightest | + +**Tier-Specific Strategies** + +| If you have... | Recommended approach | +|----------------|---------------------| +| **Limited Opus quota** | OpusPlan essential: Opus for planning, Sonnet for execution | +| **Moderate quota** | Sonnet default, Opus only for architecture/complex debugging | +| **Generous quota** | More Opus freedom, but still monitor weekly usage | +| **Unlimited/high tier** | Use Opus freely, focus on productivity over optimization | + +**The Pro User Pattern** (validated by community): + +``` +1. Opus → Create detailed plan (high-quality thinking) +2. Sonnet/Haiku → Execute the plan (cost-effective implementation) +3. Result: Best reasoning where it matters, lower cost overall +``` + +This is exactly what OpusPlan mode does automatically (see Section 2.3). + +**Monitoring Your Usage** + +```bash +/status # Shows current session: cost, context %, model +``` + +For subscription usage history: Check your [Anthropic Console](https://console.anthropic.com/settings/usage) or Claude.ai settings. + ### Context Poisoning (Bleeding) **Definition**: When information from one task contaminates another. @@ -2973,6 +3015,34 @@ CLAUDE.md files are persistent instructions that Claude reads at the start of ev └─────────────────────────────────────────────────────────┘ ``` +### Minimum Viable CLAUDE.md + +Most projects only need three things in their CLAUDE.md: + +```markdown +# Project Name + +Brief one-sentence description of what this project does. + +## Commands +- `pnpm dev` - Start development server +- `pnpm test` - Run tests +- `pnpm lint` - Check code style +``` + +**That's it for most projects.** Claude automatically detects: +- Tech stack (from package.json, go.mod, Cargo.toml, etc.) +- Directory structure (via exploration) +- Existing conventions (from the code itself) + +**Add more only when needed**: +- Non-standard package manager (yarn, bun, pnpm instead of npm) +- Custom commands that differ from standard (`npm run build` → `make build`) +- Project-specific conventions that conflict with common patterns +- Architecture decisions that aren't obvious from the code + +**Rule of thumb**: If Claude makes a mistake twice because of missing context, add that context to CLAUDE.md. Don't preemptively document everything. + ### Level 1: Global (~/.claude/CLAUDE.md) Personal preferences that apply to all your projects: @@ -3100,6 +3170,76 @@ knowledge_base: > Inspired by [Nick Tune's Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) +### CLAUDE.md in Monorepos + +Claude Code automatically discovers and merges CLAUDE.md files in monorepo hierarchies: + +``` +monorepo/ +├── CLAUDE.md # Root: org-wide standards +├── packages/ +│ ├── api/ +│ │ ├── CLAUDE.md # API-specific conventions +│ │ └── src/ +│ ├── web/ +│ │ ├── CLAUDE.md # Frontend conventions +│ │ └── src/ +│ └── shared/ +│ └── src/ +└── tools/ + └── cli/ + ├── CLAUDE.md # CLI tool specifics + └── src/ +``` + +**How it works**: +- Claude reads the root CLAUDE.md first +- When you work in `packages/api/`, it merges root + api CLAUDE.md +- More specific files add to (don't replace) parent context + +**What goes where**: + +| Location | Content | +|----------|---------| +| Root CLAUDE.md | Org standards, monorepo commands (`pnpm -w`), cross-package patterns | +| Package CLAUDE.md | Package-specific stack, local commands, unique conventions | + +**Example root CLAUDE.md for monorepo**: + +```markdown +# Acme Monorepo + +pnpm workspace. Turborepo for builds. + +## Commands +- `pnpm install` - Install all dependencies +- `pnpm build` - Build all packages +- `pnpm -F @acme/api dev` - Run API dev server +- `pnpm -F @acme/web dev` - Run web dev server + +## Cross-Package Rules +- Shared types in @acme/shared +- All packages use ESM +``` + +**Example package CLAUDE.md**: + +```markdown +# @acme/api + +Express + Prisma backend. + +## Commands +- `pnpm dev` - Start with hot reload +- `pnpm db:migrate` - Run migrations +- `pnpm db:seed` - Seed test data + +## Conventions +- Controllers in /routes +- Business logic in /services +- Prisma queries in /repositories +``` + ## 3.2 The .claude/ Folder Structure The `.claude/` folder is your project's Claude Code directory for memory, settings, and extensions. @@ -3432,10 +3572,46 @@ Files in `.claude/rules/` are automatically loaded and combined: ``` .claude/rules/ ├── code-conventions.md ──┐ -├── git-workflow.md ──┼──→ All loaded automatically +├── git-workflow.md ──┼──→ All loaded at session start └── architecture.md ──┘ ``` +### Memory Loading Comparison + +Understanding when each memory method loads is critical for token optimization: + +| Method | When Loaded | Token Cost | Use Case | +|--------|-------------|------------|----------| +| `CLAUDE.md` | Session start | Always | Core project context | +| `.claude/rules/*.md` | Session start (ALL files) | Always | Conventions that always apply | +| `@path/to/file.md` | On-demand (when referenced) | Only when used | Optional/conditional context | +| `.claude/commands/*.md` | Invocation only | Only when invoked | Workflow templates | +| `.claude/skills/*.md` | Invocation only | Only when invoked | Domain knowledge modules | + +**Key insight**: `.claude/rules/` is NOT on-demand. Every `.md` file in that directory loads at session start, consuming tokens. Reserve it for always-relevant conventions, not rarely-used guidelines. + +### Path-Specific Rules (December 2025) + +Since December 2025, rules can target specific file paths using YAML frontmatter: + +```markdown +--- +paths: + - "src/api/**/*.ts" + - "lib/handlers/**/*.ts" +--- + +# API Endpoint Conventions + +These rules only apply when working with API files: + +- All endpoints must have OpenAPI documentation +- Use zod for request/response validation +- Include rate limiting middleware +``` + +This enables progressive context loading—rules only appear when Claude works with matching files. + --- # 4. Agents @@ -4056,6 +4232,10 @@ _Quick jump:_ [Understanding Skills](#51-understanding-skills) · [Creating Skil --- +> **Note (January 2026)**: Skills and Commands are being unified. Both now use the same invocation mechanism (`/skill-name` or `/command-name`), share YAML frontmatter syntax, and can be triggered identically. The conceptual distinction (skills = knowledge modules, commands = workflow templates) remains useful for organization, but technically they're converging. Create new ones based on purpose, not mechanism. + +--- + **Reading time**: 15 minutes **Skill level**: Week 2 **Goal**: Create reusable knowledge modules @@ -4523,6 +4703,10 @@ _Quick jump:_ [Slash Commands](#61-slash-commands) · [Creating Custom Commands] --- +> **Note (January 2026)**: Skills and Commands are being unified. Both now use the same invocation mechanism (`/skill-name` or `/command-name`), share YAML frontmatter syntax, and can be triggered identically. The conceptual distinction (skills = knowledge modules, commands = workflow templates) remains useful for organization, but technically they're converging. Create new ones based on purpose, not mechanism. + +--- + **Reading time**: 10 minutes **Skill level**: Week 1-2 **Goal**: Create custom slash commands @@ -8466,6 +8650,17 @@ You: "Implement the caching layer following the plan" > **Important**: Claude Code uses lazy loading - it doesn't "load" your entire codebase at startup. Files are read on-demand when you ask Claude to analyze them. The main context consumers at startup are your CLAUDE.md files and auto-loaded rules. +**CLAUDE.md Token Cost Estimation:** + +| File Size | Approximate Tokens | Impact | +|-----------|-------------------|--------| +| 50 lines | 500-1,000 tokens | Minimal (recommended) | +| 100 lines | 1,000-2,000 tokens | Acceptable | +| 200 lines | 2,000-3,500 tokens | Upper limit | +| 500+ lines | 5,000+ tokens | Consider splitting | + +Note: These are loaded **once at session start**, not per request. A 200-line CLAUDE.md costs ~2K tokens upfront but doesn't grow during the session. The concern is the cumulative effect when combined with multiple `@includes` and all files in `.claude/rules/`. + **1. Keep CLAUDE.md files concise:** ```markdown @@ -8476,7 +8671,7 @@ You: "Implement the caching layer following the plan" # ✅ Lean CLAUDE.md - Essential project context only (<200 lines) -- Move rarely-used rules to .claude/rules/ (loaded on-demand) +- Move specialized rules to .claude/rules/ (auto-loaded at session start) - Split by concern: team rules in project CLAUDE.md, personal prefs in ~/.claude/CLAUDE.md ``` @@ -10356,4 +10551,4 @@ Thumbs.db **Contributions**: Issues and PRs welcome. -**Last updated**: January 2026 | **Version**: 3.8.2 +**Last updated**: January 2026 | **Version**: 3.9.0 diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index cef243a..14d53a8 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -3,7 +3,7 @@ # Source: guide/ultimate-guide.md # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code -version: "3.8.2" +version: "3.9.0" updated: "2026-01" # ════════════════════════════════════════════════════════════════ @@ -86,13 +86,14 @@ deep_dive: feedback_loops: 7140 batch_operations: 7570 pitfalls: 7689 - git_best_practices: 7957 - cost_optimization: 8423 - commands_table: 9076 - shortcuts_table: 9109 - troubleshooting: 9235 - cheatsheet: 9610 - daily_workflow: 9686 + git_best_practices: 8190 + subscription_limits: 1750 + cost_optimization: 8047 + commands_table: 9267 + shortcuts_table: 9300 + troubleshooting: 9426 + cheatsheet: 9801 + daily_workflow: 9877 # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier)