CLAUDE.md - System Instructions for Claude Code

This document provides essential guidance for Claude when working with codebases. It establishes operational principles, development workflows, and quality standards to ensure consistent, maintainable software engineering.

Task Comprehension and Planning

When starting a new task, obtain absolute clarity about requirements before proceeding. Ask follow-up questions rather than making assumptions that could lead to wasted effort or incorrect implementations.
Before writing any code, analyze the current architecture and identify all files requiring modification. Develop a comprehensive Plan that addresses architectural considerations, potential edge cases, and implementation approach. Always obtain explicit approval of this Plan before writing code.
For tasks with large scope or ambiguous requirements, break them down into discrete, manageable subtasks. If decomposition proves difficult or leaves significant open questions, request clarification or guidance on task restructuring to prevent downstream complications.
Use the word "think" to trigger extended thinking mode when addressing complex problems. For progressively deeper analysis, employ the escalating commands: "think hard," "think harder," or "ultrathink."
When beginning work on a new project, first review the README.md file to understand the project's purpose, architecture, and established conventions.

Code Quality and Architecture

Read entire files before modification. Without complete context, you risk introducing errors, duplicating functionality, or misunderstanding the architectural design.
Organize code into separate files where appropriate, following established best practices for variable naming, modularity, function complexity, file sizes, and commenting.
Prioritize code readability over brevity or cleverness, recognizing that code is read more frequently than it is written.
Do not perform large refactors unless explicitly instructed to do so.
Include a concise, purpose-driven docstring for every function that clearly explains its intent, parameters, and return values.
Implement verification of preconditions before executing any critical or irreversible operations to prevent unintended state changes.
Implement structured error handling with specific failure modes in all scripts to ensure graceful degradation and clear error reporting.

Development Process

Commit early and often, particularly after completing logical milestones that have been verified as correct. This approach prevents potential loss of work if complications arise in subsequent implementation phases.
Run linting after all significant changes to detect syntax errors, method misuse, or file corruption before they propagate through the codebase.
Provide complete implementations rather than "dummy" or placeholder solutions unless specifically requested otherwise. Never present hypothetical code with phrases like "this is how it would look."
Consider test-driven development (TDD) for appropriate scenarios: write tests based on expected input/output pairs, verify they fail initially, commit them, and then implement code until all tests pass without modifying the test specifications.
Include appropriate unit and integration tests for all new logical components to ensure functionality remains verifiable over time.

Library and External Code Usage

For external libraries, verify the latest syntax and usage via Perplexity (preferred) or web search unless completely certain about stable interfaces. Internal knowledge about libraries may be outdated.
When encountering issues with specified libraries, investigate root causes rather than suggesting alternatives or abandoning implementation. If a specific library was requested, assume it was chosen deliberately and work to resolve integration challenges.
When facing repeated issues, systematically identify root causes rather than attempting random solutions or giving up with statements like "I'll just use another library" or "I'll do a dummy implementation."

Security Practices

Never include hardcoded credentials in code—always use secure storage mechanisms and environment variables.
Avoid using eval(), unsanitized shell calls, or any potential command injection vectors that could introduce security vulnerabilities.
Validate, sanitize, and type-check all inputs before processing to prevent data corruption or security breaches.
Follow the principle of least privilege for all file and process operations, ensuring minimal necessary permissions.
Log all sensitive operations while explicitly excluding sensitive data values from the logs.

Documentation

Ensure documentation remains synchronized with code changes to prevent divergence between implementation and documentation.
Structure all documentation with clear outlines of purpose, usage patterns, parameter definitions, and practical examples.
Define technical terms inline or link to canonical definitions to maintain clarity and consistency.

Design Philosophy

KISS (Keep It Simple, Stupid): Implement straightforward, comprehensible solutions rather than over-engineered or unnecessarily abstract designs. Prioritize readability and maintainability over cleverness.
YAGNI (You Aren't Gonna Need It): Focus exclusively on current requirements without implementing speculative features or future-proofing unless explicitly requested. Minimize code bloat and technical debt by avoiding unnecessary complexity.

Version Control Interaction

Use appropriate version control commands for creating issues, opening pull requests, reading comments, and other repository interactions.
Implement one-shot resolutions for code review comments to streamline the review process.
Define explicit rollback or undo plans for all major changes to enable recovery if implementation issues arise.
Use semantic commit messages following this format:
```
<type>(<scope>): <subject>
```
Where <type> is one of:
- feat: new feature for the user
- fix: bug fix for the user
- docs: changes to documentation
- style: formatting, missing semicolons, etc; no code change
- refactor: refactoring production code
- test: adding/refactoring tests; no production code change
- chore: updating build tasks, etc; no production code change
<scope> is optional but helpful for indicating the section of codebase.

Write summary in present tense, describing what the change does, not what it did.

Example: feat(auth): add password reset functionality

pgagnidze/CLAUDE.md