Global Rules (CLAUDE.md)

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• skills/repo-production-workflow/SKILL.md
• skills/production-code/SKILL.md
• skills/production-preflight/SKILL.md
• skills/code-review/SKILL.md
• skills/execution-planning/SKILL.md

Global Rules establish the foundational guidance and constraints for every Claude Code session within the project. These rules prioritize architectural simplicity, production safety through hard invariants, and a strictly ordered implementation workflow. While project-specific CLAUDE.md files can override these guidelines, the global rules serve as the authoritative baseline for thinking, coding, and verification processes.

The scope of these rules covers the entire lifecycle of repository work, from initial exploration and planning to surgical implementation and final reviewer completion. By enforcing specific tools like GitNexus and mandatory skill sequences, the project ensures consistent quality and minimize technical debt.
Sources: CLAUDE.md:1-5

1. Foundational Thinking and Simplicity

The project mandates a "Think Before Coding" approach that prioritizes explicit communication and minimal implementation. Agents must state assumptions clearly and surface tradeoffs rather than picking solutions silently. The "Simplicity First" directive forbids speculative features, unnecessary abstractions, and error handling for impossible scenarios.

Simplicity Principles

• Solve the problem with the minimum amount of code.
• Delete code that could be shorter (e.g., rewrite 200 lines into 50).
• Avoid "flexibility" or "configurability" unless explicitly requested.
• Remove pre-existing dead code only if asked, but always remove dead code created by new changes.
  Sources: CLAUDE.md:7-30

2. Hard Production Invariants

Production invariants are non-negotiable gates that govern code quality and reliability. These constraints are inherited by all skills and cannot be weakened.

Invariant	Rule
Mock Ban	Tests must cross the real production Interface/Seam. Mocks, stubs, and test-only adapters are forbidden for production proof.
Imaginary-risk Ban	Theoretical failures cannot justify guards, retries, or abstractions without demonstrated occurrence.
Contradictory-contract Gate	Interfaces must not promise to accept arbitrary behavior while caveat-requiring specific caller exclusions.
Root-cause-first Gate	No production fix begins without reproduction, source tracing, and a falsifiable hypothesis.
Sources: CLAUDE.md:32-52

3. Repo Production Skill Order

Repository work follows a strict, sequential chain of skill invocations. This sequence ensures that every change is diagnosed, planned, and reviewed according to production standards.

The diagram shows the mandatory sequence of skill tool invocations for repository-scoped work.
Sources: CLAUDE.md:139-160, skills/repo-production-workflow/SKILL.md:25-100

Key Invocation Policies

• repo-production-workflow: Default first skill for any production repository work.
• repo-context-forge: Mandatory gate before choosing files or editing code. Documentation-only changes are the only exception.
• tdd: Required for behavior changes; name the real production Seam and apply the mock ban.
• production-preflight: Produces required before-edit proof, identifying reuse paths and module shapes.
  Sources: CLAUDE.md:139-145, CLAUDE.md:225-230, skills/production-preflight/SKILL.md:1-20

4. GitNexus and Search Workflow

GitNexus is the primary tool for analyzing structure, blast radius, and execution flow. It is used in conjunction with the fff MCP server for content discovery.

Search and Impact Analysis

1. Use fff for raw file and symbol discovery.
2. Switch to gitnexus for architecture and safety analysis.
3. Run mcp__gitnexus__context to see callers and callees.
4. Run mcp__gitnexus__impact with direction: upstream and includeTests: true before editing a symbol.
   Sources: CLAUDE.md:254-280

The flow describes the transition from discovery to impact analysis before implementation.
Sources: CLAUDE.md:265-275

5. Delegated Agent Defaults

When spawning sub-agents via the Agent tool, specific types and constraints apply to maintain session coherence and model hierarchy.

• subagent_type: Use Explore for codebase searches, Plan for planning-input work, and general-purpose otherwise.
• Model Inheritance: Delegates inherit the parent session's model unless CLAUDE_CODE_SUBAGENT_MODEL is set in the environment.
• Exploration Rule: Explore and Plan agents must invoke codebase-design and discover deepening opportunities rather than just locating code.
• Planning Ownership: Delegates provide inputs, but the lead agent reconciles reports and authors the final governing design.
  Sources: CLAUDE.md:112-135

6. Execution and Verification Discipline

The project enforces "Goal-Driven Execution," requiring verification loops for every task. Success is defined by concrete criteria (e.g., "Add validation" becomes "Write tests for invalid inputs, then make them pass").

Verification Requirements

• Surgical Changes: Touch only what is necessary. Clean up orphans (imports, variables) made obsolete by the change, but do not refactor unrelated code.
• Quiet Windows: Do not use sleep loops. Use ScheduleWakeup, Monitor, or CronCreate to handle merge quiet windows and scheduled follow-ups.
• Review Budget: Aim for ~500 net lines of code per PR. The split threshold is 1,000 net lines.
• Reviewer Completion Gate: Commitment/Pushing does not equal completion. Reviewer signals must be classified, and legitimate defects must be fixed before marking work complete.
  Sources: CLAUDE.md:54-110, CLAUDE.md:188-195, CLAUDE.md:208-220

PR Completion Sequence

1. Enumerate every signal (review threads, CI failures, annotations).
2. Classify items (Legitimate, Resolved, Outdated, Rejected).
3. Fix legitimate defects using repo-production-workflow.
4. Re-query head SHA and merge state after each push.
5. Close only when all threads are resolved and checks are green.
   Sources: CLAUDE.md:210-222

Global Rules ensure that development is predictable, surgical, and anchored in real production evidence rather than assumptions. By following the mandated skill order and production invariants, developers maintain the integrity of the codebase throughout the implementation lifecycle.
Sources: CLAUDE.md:290-300