AI coding is ridiculously convenient.
When you're using Claude or Cursor, writing code from scratch starts to feel pointless. Give it instructions, and working code comes out. It even writes tests for you. Development speed has definitely improved.
According to Google's research, 50% of code in the industry is now generated by AI.
research.google
In this article, I'll introduce two incredibly useful tools that I use when programming with AI coding agents.
Rather than leaving everything to AI, combining these tools dramatically improves code maintainability. And the larger your codebase becomes, the more AI agents can demonstrate their true potential.
Why Static Analysis Tools Are Necessary
Code written by AI still needs maintenance. As projects grow larger, AI struggles to grasp everything. And the worse the code quality, the worse AI's capabilities become.
AI has a constraint called the context window. There's a limit to how much code it can read at once. That's precisely why codebases need to be "readable" and "well-organized."
Specifically, here's what happens with poor-quality codebases:
- When duplicate code is scattered everywhere, AI repeatedly suggests similar fixes
- Overly complex functions are difficult even for AI to understand, leading to off-target suggestions
- When dependencies become spaghetti-like, AI misjudges the impact scope of changes
Finding these problems manually is exhausting. However, static analysis tools can detect them mechanically, consistently, and quickly.
That's why we use static analysis tools to maintain codebase quality. By eliminating problems that can be checked mechanically, AI can focus on more essential work.
Enter Ruff: The Static Analysis Tool
The Python development ecosystem was once a battlefield of competing linters.
Flake8 for code style, isort for import ordering, pydocstyle for docstrings, Bandit for security checks... Each tool needed to be installed separately, versions managed individually, and configuration file conflicts caused endless headaches. It wasn't uncommon to be exhausted just from environment setup.
Ruff ended this chaos.
Ruff comprehensively incorporates the functionality of these existing major tools. Moreover, it's not just a wrapper (a mere collection). Since the internal logic is reimplemented from scratch in Rust, it not only unifies tools but operates at astonishing speed.
"Tool management overhead" and "execution wait time." Ruff solves both of these problems—which had become bottlenecks for development speed in the AI era—with a single tool.
Enter Pyscn: A Code Design Diagnostic Tool for the AI Era
Ruff is certainly excellent. However, its scope is limited to syntax-level checks. Unused imports, naming convention violations, improper indentation—these are important, but determining whether a codebase is truly "healthy" requires deeper analysis.
Code generated by AI has common problems. Similar logic gets copied everywhere, functions bloat and become complex, and inter-module dependencies become spaghetti-like. These issues occur even when all Ruff rules pass.
This is where pyscn comes in.
pyscn is a static analysis tool that analyzes the structural quality of Python code. Built with Go and tree-sitter, it processes over 100,000 lines per second while providing the following advanced analyses:
| Analysis | What It Reveals |
|---|---|
| Cyclomatic Complexity | Detects functions that have become difficult to understand due to excessive branches and loops |
| Dead Code Detection | Finds unreachable code after return statements and dead branches after exhaustive if-elif-else |
| Code Clone Detection | Detects copy-pasted similar code using tree edit distance and suggests refactoring candidates |
| Coupling Metrics (CBO) | Visualizes dependencies between classes and warns about tightly coupled modules |
If Ruff corrects "how code is written," pyscn diagnoses "how code is designed." They don't compete—they complement each other.
# Execute instantly without installation
uvx pyscn analyze .
With just this, an HTML report is generated, visualizing the quality of your entire codebase.
Integration with AI Coding Tools: Unleashing pyscn's True Potential
pyscn's true value emerges not just from standalone use, but from combining it with AI coding tools. By passing diagnostic results to AI, you can automate complex refactoring all at once.
Use Case 1: Quality Check with Claude Code Slash Commands → Instant Refactoring
In Claude Code, you can define custom slash commands simply by placing markdown files in .claude/commands/.
<!-- .claude/commands/check-quality.md -->
Use the uvx pyscn@latest check src/ command to verify code quality. I want to refactor problematic code.
With this prepared, just typing /check-quality in Claude Code executes pyscn diagnostics and AI refactoring suggestions in one shot.
Detect high-complexity functions → Suggest function splitting → Apply on the spot. All of this completes with a single conversation.
Use Case 2: Detect Code Clones via MCP → Consolidate
In Cursor and Claude Desktop, you can call pyscn directly through MCP (Model Context Protocol).
{
"mcpServers": {
"pyscn-mcp": {
"command": "uvx",
"args": ["pyscn-mcp"]
}
}
}
After configuration, just give this instruction:
"Find duplicate code and extract it into a common function"
pyscn detects similar code using tree edit distance, and AI makes consolidation suggestions based on the results. Clone pairs found with 92% similarity are transformed into a single reusable function.
Use Case 3: Quality Gate in CI/CD
# GitHub Actions
- run: pipx run pyscn check --max-complexity 15 .
Stop the build when complexity exceeds the threshold. Even for AI-generated code, you can ensure quality through mechanical rules.
Conclusion: The Future of pyscn
pyscn is currently under active maintenance. We continuously release bug fixes and feature improvements, and actively respond to GitHub Issues and PRs.
For future development, we're preparing automatic review and fix functionality using LLMs. pyscn detects problem areas, AI automatically analyzes them and presents fix proposals—we're aiming for a world where humans just approve the suggestions.
Additionally, we're actively developing jscan, a sister tool for JavaScript/TypeScript. We'll bring the same structural analysis as pyscn to frontend development.
In an era where AI writes code, mechanisms to protect code quality become more important than ever. Use Ruff to organize syntax, use pyscn to diagnose design. With this two-tier approach, keep your codebase healthy.
uvx pyscn analyze .
First, try it on your project.
If you like it, please give us a Star on the GitHub repository. Contributions via Issues and Pull Requests are also very welcome!
See also: For more details on pyscn, check out this article:
Top comments (0)