Code Health

What Is Code Health?

Code Health is a specialized skill within the Claude Code suite, designed to automate and streamline codebase quality assessments. By leveraging the Centinela (QA) agent, this tool performs in-depth scans to identify dead code, technical debt, outdated dependencies, and various code quality issues across your entire repository. It goes beyond surface-level linting, systematically auditing both source and auxiliary directories—including tests and configuration files. The result is a comprehensive report that not only highlights problem areas but also prioritizes them for remediation, ensuring that development teams can maintain a high standard of code hygiene and technical excellence.

Why Use Code Health?

Modern software projects evolve rapidly, often accumulating a backlog of obsolete code, commented-out blocks, outdated dependencies, and lingering TODOs. Left unchecked, these issues degrade maintainability, increase the risk of bugs, and complicate onboarding for new contributors. Code Health addresses this by providing:

• Objective, repeatable quality checks before releases or after significant refactoring
• Visibility into technical debt and code smells that may otherwise go unnoticed
• Dependency audits to flag outdated or vulnerable packages
• Automated documentation of findings, enabling teams to track progress over time

Whether you're preparing for a major release, integrating a new team member, or simply aiming for continuous improvement, Code Health ensures that your codebase remains robust, secure, and easy to maintain.

How to Get Started

Integrating Code Health into your workflow is straightforward. The skill is invoked using a simple command from your development environment or chat interface:

/code-health

Upon execution, the Centinela (QA) agent initiates a multi-step scan:

1. Sign-In Checklist: Ensures all prerequisites are met and the environment is ready for scanning.
2. Comprehensive Code Analysis: Traverses all relevant directories, not just src/, but also tests/, configuration files, and auxiliary scripts.
3. Report Generation: Summarizes findings in a markdown file, typically named docs/reviews/code-health-{date}.md for easy tracking.

No additional configuration is required for basic operation, making it accessible for both small teams and large organizations.

Key Features

1. Dead Code

Detection

Code Health identifies unused imports, variables, functions, classes, and commented-out blocks. For instance, consider the following Python snippet:

import os  # Unused import

def calculate():  # Unused function
    pass

## TODO:

Remove legacy code below
## def old_function():
##     ...

The report will flag os and calculate() as dead code, and the commented-out old_function() as a candidate for removal.

2. Technical Debt and Code Smell

Analysis

The skill detects code smells such as long functions, deeply nested blocks, and duplicated code. For example:

function processData(data) {
    // 80+ lines of logic
    // Deeply nested if statements
}

Findings are categorized by severity (Critical, Warning, Suggestion) to help prioritize refactoring efforts.

3. Dependency and Vulnerability

Checks

Code Health audits your dependency manifests (e.g., package.json, requirements.txt) for outdated or insecure packages. The report will include:

• Current vs. latest package versions
• Known vulnerabilities (if detected)
• Recommendations for upgrades

4. TODO/FIXME Audit

The tool scans for TODO or FIXME comments and verifies whether they reference actual issues or tasks. This encourages actionable tracking and prevents forgotten debts.

// FIXME: Handle edge case when input is null. See ISSUE-123

5. Automated

Reporting

All findings are consolidated in a markdown report under docs/reviews/, timestamped for historical comparison. For example:

docs/reviews/code-health-2026-02-23.md

This enables teams to monitor progress and recurring issues over time.

6. Handoff to Dev

Agent

After completing the scan, Code Health prepares the findings for seamless handoff to the Dev agent, ensuring that remediation is systematically addressed.

Best Practices

• Schedule Regular Scans: Integrate /code-health into your CI/CD pipeline for continuous monitoring.
• Act on Critical Findings Promptly: Prioritize issues labeled as Critical to minimize risk.
• Track Trends Over Time: Use historical reports to identify persistent problems or improvements.
• Scan Before Major Releases: Ensure codebase cleanliness and dependency freshness prior to shipping.
• Include All Directories: Leverage Code Health’s ability to scan beyond src/, catching issues in test and config files.

Important Notes

• False Positive Mitigation: Code Health aims to minimize false positives by verifying dead code before reporting.
• Comprehensive Coverage: All relevant source, test, and configuration files are included in the scan, not just the main application code.
• Historical Comparison: Previous scan results are referenced to highlight recurring or unresolved issues.
• No Configuration Required: The default /code-health command works out of the box, but advanced customization may be possible depending on your environment.
• Delegation to Centinela (QA): All scanning is powered by the Centinela agent, ensuring consistency and reliability.

By systematically incorporating Code Health into your workflow, you can maintain a clean, maintainable, and resilient codebase—driving higher productivity and reducing long-term technical debt.