Building a Baseline-Aware Python Code Health Tool for CI and AI-Assisted Coding

The author built a Python code analysis tool called CodeClone to track structural code health over time, with a focus on separating accepted debt from new regressions. This is especially useful for teams using AI coding assistants, which can introduce locally plausible but structurally problematic changes.

Details

The author built CodeClone to address the problem of Python codebases gradually degrading in structure, even as individual changes pass tests and linting. The tool analyzes projects for various structural signals like function clones, dead code, complexity, and coupling. It produces outputs in multiple formats, all from a single canonical report, to ensure consistency between machine-readable and human-facing outputs. The key innovation is baseline-aware governance, which allows the tool to distinguish historical debt from new regressions. This is especially important for teams using AI coding assistants, which can introduce locally plausible but structurally problematic changes. The author argues that the crucial question is often not 'Is this code valid?' but 'Did this change make the repository structurally worse?', which a baseline-aware tool can answer well.