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 <noreply@anthropic.com>
2026-01-19 09:06:39 +01:00 · 2026-01-19 09:06:39 +01:00 · 7a6d369512
commit 7a6d369512
parent a5f441bcea
5 changed files with 232 additions and 16 deletions
--- 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)
--- a/README.md
+++ b/README.md
@ -6,7 +6,7 @@

 <p align="center">
  <a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/Lines-10,200+-blueviolet?style=for-the-badge" alt="Lines"/></a>
+  <a href="#"><img src="https://img.shields.io/badge/Lines-10,300+-blueviolet?style=for-the-badge" alt="Lines"/></a>
  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-62-green?style=for-the-badge" alt="Templates"/></a>
  <a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-217_questions-orange?style=for-the-badge" alt="Quiz"/></a>
 </p>
@ -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
--- 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*
--- 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
--- 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)