ccguard: Instructions file for Claude Code

ccguard

Project Goal

CCGuard is a Claude Code hook that enforces net-negative lines of code (LOC) changes. When Claude Code attempts to edit or write files, CCGuard:

1. Captures: Intercepts Edit, MultiEdit, and Write operations
2. Calculates: Counts lines added vs removed
3. Validates: Checks if changes would result in net positive LOC
4. Blocks: Prevents operations that increase total LOC
5. Guides: Provides suggestions for reducing code

This automated enforcement encourages code simplicity and thoughtful refactoring without manual reminders.

Architecture

The project follows a clean, modular architecture:

src/
├── cli/                    # CLI entry point
│   └── ccguard.ts           # Main executable
├── contracts/              # TypeScript types and Zod schemas
│   ├── types.ts           # Core interfaces
│   └── schemas.ts         # Validation schemas
├── hooks/                  # Claude Code hook processing
│   ├── processHookData.ts # Main hook processor
│   └── userPromptHandler.ts # Handle on/off commands
├── storage/               # Persistence layer
│   ├── Storage.ts        # Storage interface
│   ├── FileStorage.ts    # File-based implementation
│   └── MemoryStorage.ts  # In-memory for testing
├── validation/            # LOC validation logic
│   ├── locCounter.ts     # Line counting algorithms
│   └── validator.ts      # Main validation logic
└── ccguard/                 # State management
    └── GuardManager.ts    # Enable/disable and stats

Key Design Decisions

1. Session-Based Tracking

• Each Claude session gets its own statistics
• Cumulative tracking across all operations
• Resets don't affect other sessions

2. Line Counting Strategy

• Ignores empty lines by default (configurable)
• Counts actual code content, not whitespace
• Simple split-by-newline approach

3. Storage Abstraction

• Interface-based design for flexibility
• File storage for persistence
• Memory storage for testing

4. Validation Flow

• Pre-tool validation only (before changes applied)
• Immediate feedback on violations
• Clear, actionable error messages