claude-compass-best-practices

name	claude-compass-best-practices
description	Enforce Claude Compass development standards and best practices. This skill should be used when writing or modifying code in the Claude Compass repository, including parsers, database migrations, graph builders, MCP tools, and core services. It ensures adherence to code quality principles, proper error handling, self-documenting code, and established architectural patterns.

Claude Compass Best Practices

Overview

Maintain code quality and architectural consistency across the Claude Compass codebase by enforcing established development principles. This skill provides comprehensive guidance on code quality standards, parser development patterns, and database best practices specific to Claude Compass.

When to Apply These Standards

Apply these standards proactively when:

• Writing new code - parsers, services, utilities, MCP tools
• Modifying existing code - refactoring, bug fixes, feature enhancements
• Adding language support - new Tree-sitter parsers and grammar integrations
• Creating database migrations - schema changes, table additions, index creation
• Implementing framework detection - Vue, Laravel, React, Godot pattern recognition
• Building graph relationships - dependency detection, cross-stack connections

Core Development Principles

The Foundational Rule: No Fallback Logic

NEVER implement fallback business logic, backwards compatibility, or lazy solutions.

This principle permeates all Claude Compass development:

• Write robust, well-designed code from the start
• Avoid temporary fixes or "quick and dirty" solutions
• Do not add fallback mechanisms that mask underlying issues
• Implement proper error handling instead of silent failures
• Address root causes rather than symptoms
• Never use inline comments
• Write self-documenting code with clear naming and structure

For detailed examples and anti-patterns, consult references/code-quality-standards.md.

Self-Documenting Code

Code should be self-explanatory through clear naming and structure. Use documentation comments for methods, classes, and properties to describe their purpose, not their implementation.

Key practices:

• Clear, descriptive variable and function names
• Small, focused functions with single responsibilities
• Logical code organization and structure
• Type safety (avoid any, use proper TypeScript types)

For comprehensive naming conventions and examples, consult references/code-quality-standards.md.

Parser Development

When working with parsers or adding new language support:

Standard Parser Workflow

1. Add Tree-sitter Grammar Dependency - Install appropriate grammar package
2. Create Parser Module - Single file or modularized directory structure
3. Implement Chunking Strategy - For languages with large files (>100KB)
4. Add Comprehensive Tests - Test all language constructs and error cases
5. Register in Multi-Parser - Make parser available to the system

Tree-sitter Usage

• Use cursor-based traversal for efficiency
• Employ query-based extraction for specific patterns
• Always check node types before extracting data
• Handle errors with full context (file path, line numbers, chunk info)

Debugging Parser Issues

# Enable verbose debug logging
CLAUDE_COMPASS_DEBUG=true ./dist/src/cli/index.js analyze /path --verbose

# Debug single file (isolates parsing of one file)
./dist/src/cli/index.js analyze /path/to/repo \
  --debug-file relative/path/to/file.cs \
  --verbose

For complete parser patterns, including:

• Modularization strategies
• Chunking error handling
• Framework detection patterns
• Cross-stack dependency detection
• Performance optimization techniques

Consult references/parser-patterns.md

Database Development

All database schema changes must be done through migrations. Never modify the database schema directly.

Migration Standards

Naming: NNN_description.ts

• NNN = 3-digit sequential number (001, 002, 003, ...)
• description = kebab-case description

Structure: Every migration MUST include both up and down methods

# Create new migration
npm run migrate:make add_entity_type_column

# Apply migrations
npm run migrate:latest

# Check status
npm run migrate:status

# Rollback (if needed)
npm run migrate:rollback

Schema Design Principles

• Use appropriate, specific data types (not generic)
• Define foreign keys with proper cascade behavior (CASCADE, SET NULL, RESTRICT)
• Add indexes for columns used in WHERE, JOIN, ORDER BY clauses
• Be explicit about nullability and default values
• Use composite indexes strategically (order matters)

Query Patterns

• Always use parameterized queries (prevent SQL injection)
• Use transactions for multi-step atomic operations
• Batch large insertions for performance
• Structure joins to use indexes effectively

For complete database patterns, including:

• Service layer structure
• Transaction handling
• Vector search (pgvector) implementation
• Database testing strategies
• Migration workflow

Consult references/database-patterns.md

Modularization Strategy

Claude Compass follows strict modularization for maintainability:

When to Modularize

Modularize when a file:

• Exceeds 500 lines of code
• Contains multiple distinct responsibilities
• Would benefit from clearer separation of concerns

Directory Structure Pattern

src/parsers/<feature>/
├── index.ts              # Public API exports (backward compatibility)
├── <feature>.ts          # Main logic
├── <service-1>.ts        # Focused, single-purpose modules
├── <service-2>.ts
└── types.ts              # Shared type definitions

Examples in codebase:

• src/parsers/csharp/ - C# language parser (modularized)
• src/parsers/orm/ - ORM parsers (modularized)
• src/parsers/framework-detector/ - Framework detection (modularized)
• src/graph/builder/ - Graph construction (modularized)

Error Handling

Fail Fast, Fail Loudly

Detect and report errors as early as possible with maximum context.

Context-Rich Errors

Include all relevant information in error messages:

• File path and line numbers
• Operation being performed
• Related data (chunk index, symbol name, etc.)
• Original error cause

Example:

throw new ChunkingError(
  `Failed to parse chunk: syntax error in object literal`,
  {
    filePath: '/path/to/file.ts',
    chunkIndex: 3,
    totalChunks: 5,
    startLine: 250,
    endLine: 499,
    cause: originalError
  }
);

Testing Requirements

Every feature or bug fix should include tests:

• Parsers: Test each language construct (classes, functions, imports)
• Graph builders: Test relationship detection and edge cases
• Database operations: Test CRUD operations and queries
• MCP tools: Integration tests for each tool
• Error handling: Test that errors include proper context

Test files: tests/**/*.test.ts

Reference Files

This skill includes three comprehensive reference documents:

1. Code Quality Standards (references/code-quality-standards.md)

Load when:

• Writing new code that needs architectural guidance
• Refactoring existing code for quality improvements
• Reviewing code for adherence to standards
• Questions about self-documenting code or naming conventions

Contains:

• Detailed fallback logic anti-patterns
• Self-documenting code examples
• Modularization patterns and checklists
• Error handling philosophy
• Type safety guidelines
• Testing requirements

2. Parser Patterns (references/parser-patterns.md)

Load when:

• Adding support for a new programming language
• Working with Tree-sitter parsing logic
• Implementing or debugging chunking strategies
• Adding framework detection capabilities
• Detecting cross-stack dependencies

Contains:

• Complete language support workflow (5 steps)
• Tree-sitter cursor traversal patterns
• Query-based extraction techniques
• Chunking error handling strategies
• Framework detection patterns
• Performance optimization techniques

3. Database Patterns (references/database-patterns.md)

Load when:

• Creating database migrations
• Designing new tables or schema changes
• Writing database queries or services
• Implementing vector search with pgvector
• Working with database transactions

Contains:

• Migration naming and structure standards
• Schema design principles (types, foreign keys, indexes)
• Query patterns (parameterized queries, transactions, batching)
• Service layer architecture
• Vector search implementation
• Migration workflow and rollback strategies

Quick Decision Guide

Use this guide to determine which reference to consult:

Task	Reference to Load
Writing a new function/class	code-quality-standards.md
Adding language support (Rust, Go, etc.)	parser-patterns.md
Creating database migration	database-patterns.md
Implementing Tree-sitter parsing	parser-patterns.md
Designing database schema	database-patterns.md
Refactoring for code quality	code-quality-standards.md
Debugging parser errors	parser-patterns.md
Writing database queries	database-patterns.md
Modularizing a large file	code-quality-standards.md
Adding framework detection	parser-patterns.md

Progressive Consultation

Start with the relevant reference sections and load additional context as needed:

1. Identify the task - Determine which category (code quality, parser, database)
2. Load relevant reference - Consult the appropriate reference file
3. Apply patterns - Follow established patterns and examples
4. Verify compliance - Ensure adherence to core principles