AI Code Refactoring Pipeline: A Four-Stage Architecture Integrating LLM into Software Engineering Practice

This article introduces the ai-refactoring-pipeline project, an end-to-end code refactoring processing pipeline. Through four stages—chunking (cAST), prompt construction, LLM agent, and validation—it converts source code into high-quality structured input, helping development teams address the issues of low efficiency and high defect introduction risk in traditional manual refactoring, and systematically integrating LLM capabilities to achieve intelligent code refactoring.

In software development, code refactoring is an important but time-consuming task. As project scale grows, technical debt tends to accumulate, and manual refactoring is inefficient and prone to introducing defects. LLM's ability in code understanding provides possibilities for automated refactoring, but directly using raw code has issues like context window limitations and lack of design intent understanding. Thus, a systematic preprocessing flow is needed, leading to the birth of the ai-refactoring-pipeline project.

The project's core is a four-stage pipeline:

1. cAST Stage: Split code into semantically complete chunks via Abstract Syntax Tree (AST) analysis, output JSON with metadata;
2. Prompt Builder Stage: Construct context-rich structured prompts based on code type, complexity, etc.;
3. LLM Refactoring Agent: Send prompts to LLM (e.g., Gemini), implement batch processing and throttling mechanisms to handle API limitations;
4. Validator Stage: Verify the grammatical correctness, functional equivalence, and style consistency of refactored code, and generate reports.

The project is implemented in Python with a clear directory structure: the backend contains core pipeline modules, input stores files to be refactored, and output saves results. Run it via orchestrate.py, which supports multiple modes: single file/batch directory processing, batch control, throttling delay, model selection (e.g., Gemini), in-place replacement, and other parameters.

This tool is suitable for: modernization of legacy codebases, preprocessing for code reviews (fixing common code smells), and developers learning refactoring best practices. The project provides comprehensive documentation (system design, audit reports, failure strategies, etc.) to help users use and extend it.

In the future, a web-based visual dashboard will be developed to lower the usage threshold. The project demonstrates how to systematically integrate LLM capabilities into software engineering practices, maximizing LLM potential through preprocessing and postprocessing flows, and serves as a reference implementation for AI-assisted code refactoring.