Skip to content

Commit 1a7528b

Browse files
JeremyDev87JeremyDev87
committed
docs(claude-code): slim AI instructions to reduce session token cost
Reduces the text Claude Code auto-injects at every session start from ~6,802 tokens to ~3,097 tokens (−3,705 tokens / −54.5%, measured with char/3.5 approximation) by: - Moving the full agent catalog out of custom-instructions.md. Agent metadata is now fetched on demand via mcp__codingbuddy__get_agent_details / list_agent_stacks, and the canonical list lives in packages/rules/.ai-rules/agents/README.md. Saves ~2,590 tokens/session. - Relocating permission-presets.md from .claude/rules/ (auto-loaded into every session) to docs/claude-code/ (reference material, not auto-loaded). Saves ~1,073 tokens/session. CLAUDE.md gets a one-line pointer to the new location so discoverability stays intact. The file move is byte-identical and git detects it as a rename. - Trimming CLAUDE.md's Tool Priority section to a layered summary with a link to .claude/rules/tool-priority.md for the full matrix. Saves ~42 tokens/session. All three MANDATORY rules are preserved verbatim in custom-instructions.md: - TDD_CONTINUITY_RULE (line 31) - CODINGBUDDY_CRITICAL_RULE — keyword mode detection (line 48) - SPECIALIST_COUNCIL_RULE (line 61) No behavioral change for any Claude Code session. Only the per-session context size drops. Cache-invalidation note: the first few sessions after this merge will re-cache the new prompt, so initial savings apply from roughly the second session onward. Also gitignores .claude/worktrees/ and .local-backups/ — both are local runtime/backup artifacts that were incorrectly surfacing as untracked and should never be committed. Original work by Codex running a token-reduction prompt; verified by Claude Code for mandatory-rule preservation, path consistency, downstream references, and actual token measurement.
1 parent af0d12b commit 1a7528b

4 files changed

Lines changed: 59 additions & 154 deletions

File tree

‎.claude/rules/custom-instructions.md‎

Lines changed: 50 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,193 +1,93 @@
11
# Custom Instructions for Claude Code
22

3-
## Project Rules
4-
5-
Follow the common rules defined in `packages/rules/.ai-rules/` for consistency across all AI coding assistants.
6-
7-
### 📚 Core Workflow
8-
9-
**Source**: `packages/rules/.ai-rules/rules/core.md`
10-
11-
**Work Modes**:
12-
- **PLAN mode**: Create implementation plans with TDD approach
13-
- **ACT mode**: Execute changes following quality standards
14-
- **EVAL mode**: Evaluate code quality and suggest improvements
15-
- **AUTO mode**: Autonomous PLAN → ACT → EVAL cycle until quality achieved
16-
17-
**Mode Flow**: PLAN (default) → ACT (user types "ACT") → PLAN (automatic) → EVAL (user types "EVAL") | AUTO (autonomous cycle)
18-
19-
**Mode Indicators**: Display `activation_message.formatted` from the `parse_mode` response (e.g., `🤖 agent-name [Primary Agent]`), then print `# Mode: PLAN|ACT|EVAL|AUTO` and `## Agent : [Agent Name]` at the start of responses
20-
21-
### 🏗️ Project Context
22-
23-
**Source**: `packages/rules/.ai-rules/rules/project.md`
24-
25-
**Tech Stack**: See project's `package.json`
26-
27-
**Architecture**:
28-
- Layered structure: app → widgets → features → entities → shared
29-
- Pure/impure function separation required
30-
- Server Components as default
31-
32-
### 🎯 Code Quality
33-
34-
**Source**: `packages/rules/.ai-rules/rules/augmented-coding.md`
35-
36-
**TDD Cycle**: Red (failing test) → Green (minimal code) → Refactor
37-
38-
**Principles**:
39-
- TDD for core logic (entities, shared/utils, hooks)
40-
- Test-after for UI (features, widgets)
41-
- SOLID principles, DRY, 90%+ test coverage
42-
- No mocking - test real behavior
43-
- TypeScript strict mode (no `any`)
44-
45-
### 🤖 Specialist Agents
46-
47-
**Source**: `packages/rules/.ai-rules/agents/`
48-
49-
**Available Agents**:
50-
51-
| Agent | Description | Expertise |
52-
|-------|-------------|-----------|
53-
| Accessibility Specialist | Accessibility expert for Planning, Implementation, and Evaluation modes - unified specialist for WCAG 2.1 AA compliance, ARIA attributes, and keyboard navigation | |
54-
| Act Mode Agent | ACT mode agent - specialized for actual implementation execution | |
55-
| Agent Architect | Primary Agent for creating, validating, and managing AI agent configurations | |
56-
| AI/ML Engineer | AI/ML expert for Planning, Implementation, and Evaluation modes - unified specialist for LLM integration, prompt engineering, RAG architecture, AI safety, and testing non-deterministic systems | |
57-
| Architecture Specialist | Architecture expert for Planning, Implementation, and Evaluation modes - unified specialist for layer placement, dependency direction, and type safety | |
58-
| Auto Mode Agent | AUTO mode agent - autonomous PLAN → ACT → EVAL cycle until quality targets met | |
59-
| Backend Developer | Language-agnostic backend specialist with Clean Architecture, TDD, and security focus. Supports Node.js, Python, Go, Java, and other backend stacks. | |
60-
| Code Quality Specialist | Code quality expert for Planning, Implementation, and Evaluation modes - unified specialist for SOLID principles, DRY, complexity analysis, and design patterns | |
61-
| Code Reviewer | Senior software engineer specializing in comprehensive code quality evaluation and improvement recommendations | |
62-
| Data Engineer | Data specialist focused on database design, schema optimization, migrations, and analytics query optimization. Handles data modeling, ETL patterns, and reporting data structures. | |
63-
| Data Scientist | Data science specialist for exploratory data analysis, statistical modeling, ML model development, and data visualization. Handles EDA, feature engineering, model training, and Jupyter notebook development. | |
64-
| DevOps Engineer | Docker, Datadog monitoring, and Next.js deployment specialist | |
65-
| Documentation Specialist | Documentation expert for Planning, Implementation, and Evaluation modes - unified specialist for documentation planning, code comments, type definitions, and documentation quality assessment | |
66-
| Eval Mode Agent | EVAL mode agent - specialized for code quality evaluation and improvement suggestions | |
67-
| Event Architecture Specialist | Event-driven architecture specialist for Planning, Implementation, and Evaluation modes - unified specialist for message queues, event sourcing, CQRS, real-time communication, distributed transactions, and event schema management | |
68-
| Frontend Developer | Modern React/Next.js specialist with Server Components/Actions, TDD, and accessibility focus | |
69-
| i18n Specialist | Internationalization expert for Planning, Implementation, and Evaluation modes - unified specialist for i18n library setup, translation key structure, formatting, and RTL support | |
70-
| Integration Specialist | External service integration specialist for Planning, Implementation, and Evaluation modes - unified specialist for API integrations, webhooks, OAuth flows, and failure isolation patterns | |
71-
| Migration Specialist | Cross-cutting migration coordinator for legacy system modernization, framework upgrades, database migrations, and API versioning - unified specialist for Strangler Fig, Branch by Abstraction, and zero-downtime migration patterns | |
72-
| Mobile Developer | Cross-platform and native mobile specialist supporting React Native, Flutter, iOS (Swift/SwiftUI), and Android (Kotlin/Compose). Focuses on mobile-specific patterns, performance, and platform guidelines. | |
73-
| Observability Specialist | Observability expert for Planning, Implementation, and Evaluation modes - unified specialist for vendor-neutral monitoring, distributed tracing, structured logging, SLI/SLO frameworks, and alerting patterns | |
74-
| Parallel Orchestrator | Orchestrates parallel execution of multiple GitHub issues using taskMaestro with file-overlap validation, Wave grouping, and AUTO mode workers | |
75-
| Performance Specialist | Performance expert for Planning, Implementation, and Evaluation modes - unified specialist for bundle size optimization, rendering optimization, and Core Web Vitals | |
76-
| Plan Mode Agent | PLAN mode agent - specialized for work planning and design | |
77-
| Plan Reviewer | Reviews implementation plans for quality, completeness, and feasibility before execution | |
78-
| Platform Engineer | Cloud-native infrastructure expert for Planning, Implementation, and Evaluation modes - unified specialist for Infrastructure as Code, Kubernetes orchestration, multi-cloud strategy, GitOps workflows, cost optimization, and disaster recovery | |
79-
| Security Engineer | Primary Agent for implementing security features, fixing vulnerabilities, and applying security best practices in code | |
80-
| Security Specialist | Security expert for Planning, Implementation, and Evaluation modes - unified specialist for authentication, authorization, and security vulnerability prevention | |
81-
| SEO Specialist | SEO expert for Planning, Implementation, and Evaluation modes - unified specialist for metadata, structured data, and search engine optimization | |
82-
| Software Engineer | General-purpose implementation engineer — any language, any domain, TDD-first | |
83-
| Solution Architect | High-level system design and architecture planning specialist | |
84-
| Systems Developer | Primary Agent for systems programming, low-level optimization, native code development, and performance-critical implementations | |
85-
| Technical Planner | Low-level implementation planning with TDD and bite-sized tasks | |
86-
| Test Engineer | Primary Agent for TDD cycle execution, test writing, and coverage improvement across all test types | |
87-
| Test Strategy Specialist | Test strategy expert for Planning, Implementation, and Evaluation modes - unified specialist for TDD vs Test-After decisions, test coverage planning, and test quality assessment | |
88-
| Tooling Engineer | Project configuration, build tools, and development environment specialist | |
89-
| UI/UX Designer | UI/UX design specialist based on universal design principles and UX best practices - focuses on aesthetics, usability, and user experience rather than specific design system implementations | |
90-
91-
See [packages/rules/.ai-rules/agents/README.md](../../packages/rules/.ai-rules/agents/README.md) for details.
3+
Follow the common rules in `packages/rules/.ai-rules/` for consistency across AI assistants.
924

93-
## 🔴 MANDATORY: TDD Execution Continuity
5+
## 📚 Core Workflow — Modes
946

95-
<TDD_CONTINUITY_RULE>
7+
- **PLAN**: Create implementation plans with TDD approach
8+
- **ACT**: Execute changes following quality standards
9+
- **EVAL**: Evaluate code quality and suggest improvements
10+
- **AUTO**: Autonomous PLAN → ACT → EVAL cycle
11+
12+
**Mode indicators**: Display `activation_message.formatted` from `parse_mode`, then `# Mode: PLAN|ACT|EVAL|AUTO` at start of response.
13+
14+
## 🎯 Code Quality
9615

97-
**TDD RED phase test failures are expected results and are NOT a reason to halt implementation.**
16+
- **TDD cycle**: Red → Green → Refactor (atomic operation)
17+
- TDD for core logic; test-after for UI
18+
- SOLID, DRY, 90%+ coverage
19+
- TypeScript strict (no `any`)
20+
- No mocking — test real behavior
9821

99-
### Test Failure Classification
22+
## 🤖 Specialist Agents
10023

101-
| Type | Description | Action |
102-
|------|-------------|--------|
103-
| **Expected RED** | Intentional test failure in TDD RED phase | Proceed to GREEN phase immediately |
104-
| **Unexpected Failure** | Test that should pass but doesn't | Stop and analyze root cause |
24+
Agent list is **not duplicated here** — fetch on demand:
25+
- `mcp__codingbuddy__get_agent_details(agentName)` — profile, expertise, system prompt
26+
- `mcp__codingbuddy__list_agent_stacks` — all available agents
27+
- Full list: [packages/rules/.ai-rules/agents/README.md](../../packages/rules/.ai-rules/agents/README.md)
10528

106-
### RED-GREEN-REFACTOR is an Atomic Operation
29+
## 🔴 MANDATORY: TDD Execution Continuity
30+
31+
<TDD_CONTINUITY_RULE>
10732

108-
1. **RED**: Write failing test -> Run to confirm failure -> **DO NOT STOP**
109-
2. **GREEN**: Write minimal implementation -> Run to confirm pass
110-
3. **REFACTOR**: Refactor -> Confirm tests still pass
33+
TDD RED phase test failures are **expected results** and are NOT a reason to halt implementation.
11134

112-
**Do not wait for user input until all three phases are complete.**
35+
| Type | Action |
36+
|------|--------|
37+
| **Expected RED** (intentional failure) | Proceed to GREEN immediately |
38+
| **Unexpected failure** | Stop and analyze root cause |
11339

114-
### TDD Step Handling During Plan Execution
40+
**RED → GREEN → REFACTOR is atomic** — do not wait for user input until all three phases are complete.
11541

116-
Even if plan separates TDD into individual steps (e.g., Step 1: Write test, Step 2: Verify fails, Step 3: Implement):
117-
- When a step containing **"Expected: FAIL" or "verify it fails"** results in test failure -> Proceed to next step immediately
118-
- This **takes precedence** over the executing-plans skill's "STOP on test fail" rule
42+
When a plan step contains "Expected: FAIL" or "verify it fails", a test failure means **proceed to next step**. This takes precedence over executing-plans "STOP on test fail" rule.
11943

12044
</TDD_CONTINUITY_RULE>
12145

12246
## 🔴 MANDATORY: Keyword Mode Detection
12347

12448
<CODINGBUDDY_CRITICAL_RULE>
12549

126-
**When user message starts with PLAN, ACT, EVAL, or AUTO keyword (or localized equivalents):**
50+
When user message starts with PLAN, ACT, EVAL, or AUTO (or localized equivalents):
12751

128-
1. Call `activate` MCP tool with the user's prompt (preferred in Claude Code)
129-
2. **Fallback**: Call `parse_mode` if `activate` is unavailable
130-
3. Follow the returned `rules` as context
131-
4. Use returned `specialists` to run a council via Claude native Teams
52+
1. Call `activate` MCP tool (preferred in Claude Code)
53+
2. Fallback: `parse_mode` if `activate` unavailable
54+
3. Follow returned `rules` as context
55+
4. Use returned `specialists` for council via Claude native Teams
13256

13357
</CODINGBUDDY_CRITICAL_RULE>
13458

135-
## 🔴 MANDATORY: Specialist Council Execution
59+
## 🔴 MANDATORY: Specialist Council
13660

13761
<SPECIALIST_COUNCIL_RULE>
13862

139-
**When `activate` returns specialists, run them as a council via Claude native Teams.**
63+
When `activate` returns specialists, run as council via Claude native Teams:
14064

141-
### Workflow
142-
143-
1. Call `activate({ prompt })` → get rules, primaryAgent, specialists
144-
2. Create a Claude native Team with the returned specialists as teammates
145-
3. Each specialist independently analyzes the task
146-
4. Specialists cross-review each other's findings
65+
1. `activate({ prompt })` → rules, primaryAgent, specialists
66+
2. Create Claude native Team with specialists as teammates
67+
3. Each specialist independently analyzes
68+
4. Cross-review findings
14769
5. Collect consensus: approve | concern | reject
148-
6. Summarize all findings to user
149-
150-
### Fallback (non-Teams environments)
70+
6. Summarize to user
15171

152-
If Teams is not available, dispatch specialists as parallel subagents:
153-
- Use `Agent` tool with `run_in_background: true` for each specialist
154-
- Collect results and synthesize
72+
**Fallback** (non-Teams): dispatch specialists as parallel subagents via Agent tool with `run_in_background: true`.
15573

15674
</SPECIALIST_COUNCIL_RULE>
15775

15876
## Claude Code Native Feature Mapping
15977

160-
Use Claude Code native features instead of codingbuddy equivalents:
78+
Prefer native features over codingbuddy equivalents:
16179

162-
| Need | Native Feature | Instead of |
163-
|------|----------------|------------|
80+
| Need | Native | Instead of |
81+
|------|--------|------------|
16482
| Cross-session context | **Claude Code Memory** | `update_context` / `create_briefing` / `resume_session` |
165-
| Specialist debate | **Claude native Teams** | `dispatch_agents` subagent strategy |
83+
| Specialist debate | **Claude native Teams** | `dispatch_agents` |
16684
| Task exploration | **/dream** | `analyze_task` |
16785
| Planning with approval | **EnterPlanMode** | `parse_mode` planning stage |
16886
| Repeated execution | **/loop** | AUTO mode repetition |
16987
| Clarification | **AskUserQuestion** | clarification gate |
17088

171-
## Claude Code Specific
172-
173-
- Follow project's configured language setting
174-
- Use structured markdown formatting
175-
- Provide clear, actionable feedback
176-
- Reference project context from `packages/rules/.ai-rules/rules/project.md`
177-
- Follow PLAN → ACT → EVAL workflow when appropriate
178-
17989
## Full Documentation
18090

181-
For comprehensive guides:
182-
- **augmented-coding**: [packages/rules/.ai-rules/rules/augmented-coding.md](../../packages/rules/.ai-rules/rules/augmented-coding.md)
183-
- **clarification-guide**: [packages/rules/.ai-rules/rules/clarification-guide.md](../../packages/rules/.ai-rules/rules/clarification-guide.md)
184-
- **core**: [packages/rules/.ai-rules/rules/core.md](../../packages/rules/.ai-rules/rules/core.md)
185-
- **parallel-execution**: [packages/rules/.ai-rules/rules/parallel-execution.md](../../packages/rules/.ai-rules/rules/parallel-execution.md)
186-
- **project**: [packages/rules/.ai-rules/rules/project.md](../../packages/rules/.ai-rules/rules/project.md)
187-
- **structured-reasoning-guide**: [packages/rules/.ai-rules/rules/structured-reasoning-guide.md](../../packages/rules/.ai-rules/rules/structured-reasoning-guide.md)
188-
- **Agents System**: [packages/rules/.ai-rules/agents/README.md](../../packages/rules/.ai-rules/agents/README.md)
189-
- **Claude Integration**: [packages/rules/.ai-rules/adapters/claude-code.md](../../packages/rules/.ai-rules/adapters/claude-code.md)
190-
191-
---
192-
193-
**Note**: These instructions reference common AI rules from `packages/rules/.ai-rules/` directory shared across all AI assistants (Cursor, Claude Code, Antigravity, Codex, Q, Kiro) for consistency.
91+
Rules: [packages/rules/.ai-rules/rules/](../../packages/rules/.ai-rules/rules/)
92+
Agents: [packages/rules/.ai-rules/agents/README.md](../../packages/rules/.ai-rules/agents/README.md)
93+
Claude adapter: [packages/rules/.ai-rules/adapters/claude-code.md](../../packages/rules/.ai-rules/adapters/claude-code.md)

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,10 @@ coverage/
4848

4949
# Worktrees
5050
.worktrees/
51+
.claude/worktrees/
52+
53+
# Local backup snapshots (never committed)
54+
.local-backups/
5155

5256
# AI
5357
.mcp.json

‎CLAUDE.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,13 @@ codingbuddy/
3232

3333
## Tool Priority
3434

35-
**Principle:** codingbuddy first, OMC for unique features only.
35+
**Layered priority**: Claude Code native → codingbuddy → OMC.
3636

37-
- **codingbuddy FIRST**: `parse_mode`, `dispatch_agents`, `analyze_task`, `update_context`, `generate_checklist`, `search_rules`, `pr_quality_report`, `create_briefing`, `resume_session`, `get_rule_impact_report`
38-
- **OMC only**: LSP tools, AST grep, Python REPL, state/notepad, git-master, build-fix, deepsearch, team/swarm
37+
See [`.claude/rules/tool-priority.md`](.claude/rules/tool-priority.md) for the full decision matrix.
3938

40-
See [`.claude/rules/tool-priority.md`](.claude/rules/tool-priority.md) for full details.
39+
## Permission Presets
40+
41+
See [`docs/claude-code/permission-presets.md`](docs/claude-code/permission-presets.md) for parallel-execution and development preset definitions.
4142

4243
## Commands
4344

.claude/rules/permission-presets.md renamed to docs/claude-code/permission-presets.md

File renamed without changes.

0 commit comments

Comments
 (0)