\section{Introduction}
\label{sec:intro}

% Code Fundation AGI
% 提升准确性
% 找到中间表示
%% 描述清楚场景 面向更加general的场景， 使用AI像程序员一样去规划 所以要有high level的问题。如果要让用户把所有detail都规划清楚其实是很困难的。 需求到implementaion是有很大的gap的。更难的问题。 巨大的gap，需要用户写很多的文档，没有很多的程序知识，让用户去写没有办法做很好的规划。

% 解释unstable
Recent large language models (LLMs) have shown strong performance on function-level and file-level code generation, reliably producing functions and files from natural language descriptions~\citep{zhu2024deepseek, wang2025epicoder, liu2025rstar, zeng2025acecoder}.  However, scaling this capability from functions and files to generate large-scale software repositories from scratch remains a fundamental challenge. The core difficulty is bridging the gap between high-level user intent and the repository’s intricate network of files, classes, and dependencies\cite{tao2025code, li2025mrg}. 
Successfully navigating this gap necessitates a process of progressive planning, which naturally decomposes into two complementary phases: \textbf{proposal-level planning}, which determines \textit{what to build} by defining the functional scope and key capabilities, and \textbf{implementation-level planning}, which determines \textit{how to build} it by specifying the file structure, interfaces, dependencies, and data flows.

Prior work has explored this challenge through three paradigms. Distributed planning frameworks (e.g., MetaGPT~\citep{hong2023metagpt}, ChatDev~\citep{qian2023chatdev}) assign specialized roles such as manager, architect, and engineer to negotiate between requirements and implementations. Workflow-based systems (e.g., Paper2Code~\citep{seo2025paper2code}, AutoP2C~\citep{lin2025autop2c}) follow fixed pipelines that first build architectural skeletons before filling in details. Iterative terminal agents (e.g., OpenHands~\citep{wang2024openhands}, Claude Code~\citep{anthropic_claude_code_2025}, Gemini CLI~\citep{google2025geminicli}) externalize intermediate plans, often in markdown, and refine them step by step. Despite their differences, these approaches share a dependency: natural language as the intermediate medium for planning.

While natural language remains a flexible and human-readable medium, it can often be less efficient for large-scale repository generation. Its inherent ambiguity may blur distinctions between intent and constraints~\citep{wang2024planning}, its lack of explicit hierarchy makes dependency tracking particularly difficult~\citep{besta2024graph}, and static plans may gradually degrade over long horizons without adaptive adjustment~\citep{sun2023adaplanner}. When extended to automatic repository generation, these limitations can more easily lead to unstable proposal-level planning, where functionalities are sometimes incomplete, overlapping, or unevenly scoped~\citep{zhu2025adacoder}, and fragmented implementation-level planning, where plans drift across iterations, introducing inconsistencies in dependencies, data flows, and modular boundaries~\citep{almorsi2024guided, ashrafi2025enhancing}.

To address these limitations, we introduce the Repository Planning Graph (\graph{}), a persistent and evolvable representation that unifies proposal and implementation planning for repository generation. \graph{} encodes functional goals and designs in a single graph: nodes capture hierarchical capabilities with files, classes, and functions, while edges specify semantic relations and data flows. By replacing free-form language with a structured medium, \graph{} provides a compact, interpretable basis for consistent long-horizon planning. Building on this representation, we develop \ours{}, a graph-driven framework for controllable repository generation. Given a user specification, \ours{} proceeds in three stages: (1) \textbf{Proposal-Level Construction}, which organizes and refines requirements into a functional graph via a large-scale feature tree; (2) \textbf{Implementation-Level Construction}, which expands this graph into the full \graph{} by encoding file skeletons, interfaces, and flows; and (3) \textbf{Graph-Guided Code Generation}, which traverses the \graph{} in topological order with test-driven development, guided localization, and iterative editing.

To evaluate agents’ planning ability in repository generation, we construct \textbf{RepoCraft}, a benchmark of six projects with 1,052 tasks. On RepoCraft, \ours{} attains 81.5\% functional coverage and a 69.7\% pass rate, exceeding the strongest baseline (Claude Code) by 27.3 and 35.8 points, while producing repositories with 36K Lines of Code and 445K Code Tokens, about 3.9× larger than Claude Code and 68× larger than other baselines. Further analysis shows that \textbf{Repository Planning Graph} (\graph{}) captures complex dependencies, including inter-module data flows and function-level relations. It enables near-linear scaling of functionality and code size, supporting complex planning and providing a foundation for large-scale repositories and long-horizon development. As a global representation, \graph{} enhances agents’ repository understanding and accelerates localization.

Our Contributions are list below:
\vspace*{-5pt}
\begin{enumerate}
\item We introduce the Repository Planning Graph (\graph{}), a unified representation integrating proposal- and implementation-level planning, encoding functionality, file structures, data flows, and function designs.
\vspace*{-1pt}
\item We develop \ours{}, a graph-driven framework that constructs \graph{} through proposal- and implementation-level planning, and generates code with test validation.
\vspace*{-1pt}
\item To evaluate agent planning ability in repository generation, we build \textbf{RepoCraft}, a benchmark of 6 projects with 1{,}052 tasks assessing coverage, accuracy, and code scale.
\vspace*{-1pt}
\item On RepoCraft, \ours{} achieves strong improvements over baselines, reaching 81.5\% functional coverage and nearly 69.7\% test accuracy, while producing repositories 3.9× larger than the strongest baseline. Further analysis shows that \graph{} captures complex dependencies, enables more sophisticated planning through near-linear scaling, and enhances agents’ repository understanding, thereby accelerating localization.
\end{enumerate}




% Recent large language models (LLMs) have shown strong performance on function-level code generation, reliably producing functions and files from natural language descriptions~\cite{zhu2024deepseek, wang2025epicoder, liu2025rstar, zeng2025acecoder}. To move toward artificial general intelligence (AGI), LLMs must be able to construct complete software systems, a process that integrates planning, implementation, and debugging under complex functional and dependency constraints. 


% User inputs are often short and abstract, since producing detailed design specifications requires substantial engineering expertise. By contrast, a full repository spans numerous functionalities and intricate dependencies, leaving a wide gap between high-level intent and executable systems. Bridging this gap demands two complementary forms of planning: (1) \textbf{proposal-level planning}, which defines functional boundaries, organizes capabilities, and identifies concrete features (e.g., algorithms) to be realized; and (2) \textbf{implementation-level planning}, which translates these functional proposals into executable blueprints through file structures, data flows, interface designs, and dependency relations. Together, these capabilities enable agents to progressively refine user intent into coherent repositories.


% First, \textbf{proposal-level planning becomes unstable.} Lacking a systematic way to enumerate capabilities, multi-agent and staged-workflow systems often generate incomplete or narrowly scoped functionality sets~\citep{hong2023metagpt, qian2023chatdev, seo2025paper2code}. This instability also manifests as inconsistent granularity; for the same requirement, a system like Claude Code might produce a detailed API specification on one run and a vague three-tier architecture (\textit{frontend--backend--database}) on the next~\citep{anthropic2025claudecode}. Second, \textbf{implementation-level planning becomes fragmented.} Without a persistent, structured representation to track dependencies, natural language plans fail to capture long-horizon connections. Consequently, systems like Gemini Cli often generate shallow file skeletons with underspecified classes~\citep{google2025geminicli}, or, like Codex, prematurely stagnate after only a few planning iterations~\citep{openai_codex_2025}.



% While these paradigms differ in execution, they share a critical vulnerability: a reliance on natural language as the primary intermediate representation for planning. We argue this is a fundamental limitation. Natural language, while ideal for human-computer interaction, is an inherently ambiguous, unstructured, and inconsistent medium for representing the complex, formal relationships within a software project~

% Although these paradigms differ in how they organize reasoning, they share a reliance on natural language as the medium for repository-scale planning. However, natural language is inadequate as an intermediate representation: it is inherently ambiguous, redundant, and inconsistent~\cite{sun2023adaplanner, besta2024graph}, and even small variations in wording can significantly alter downstream outcomes~\cite{wang2024planning}. Our preliminary analysis of prior frameworks further illustrates these limitations: (1) \textbf{Unstable Proposal-level Planning}  
% Because natural language provides no systematic way to enumerate and organize capabilities, multi-agent and staged-workflow systems~\citep{hong2023metagpt, qian2023chatdev, seo2025paper2code} often produce narrowly scoped functionality sets, omitting essential components. Claude Code~\cite{anthropic2025claudecode} exemplifies a different form of instability, manifested as inconsistency in the granularity of generated plans. For identical input requirements, the system may at times produce highly detailed specifications encompassing API endpoints, database schemas, and UI components, while in other cases it outputs only a coarse three-tier architecture (\textit{frontend–backend–database}). This inconsistency highlights the volatility of natural language as an intermediate representation for functional planning. (2) \textbf{Fragmented Implementation-level Planning} Once functionalities are identified, natural language provides no persistent structure to capture long-horizon dependencies across development steps. Consequently, systems such as Gemini Cli~\citep{google2025geminicli} often generate only shallow skeletons with plain file and module structures, while the design of functions and classes remains underspecified. Similarly, Codex~\citep{openai_codex_2025} tends to stagnate within the early iterations, ceasing to propose new functionalities after only limited rounds of planning. These patterns highlight the fragmentation that arises when implementation planning relies solely on natural language descriptions.





% Although these paradigms differ in how they organize reasoning, they share a common reliance on natural language as the medium for repository design and implementation planning. In practice, this unstructured representation introduces two major problems:
% (1) \textbf{Unstable Proposal-level Planning.} Repository development requires a sufficient and coherent set of functionalities, yet natural language provides no reliable medium for systematic capability planning. Frameworks often generate incomplete or inconsistent proposals, with key functionalities omitted or redundantly described. The high variability of natural language further allows the same intent to be expressed in many different forms, making proposals unstable and difficult to control. This instability at the planning stage propagates uncertainty into subsequent implementation. (2) \textbf{Fragmented Implementation-level Planning.} Even when functionalities are identified, carrying them through to coherent implementations remains difficult. Natural language provides no persistent structure for tracking long-horizon dependencies, causing agents to lose context as development progresses. This often results in fragmented execution, such as duplicated or abandoned functions, and incoherent workflows.

% Although these paradigms differ in form, the repositories they produce consistently fall short of the depth, modularity, and robustness of human-written software. Such flaws, we argue, are not random but stem directly from a fragile planning process. We attribute this to a shared reliance on natural language as the primary medium for planning and reasoning. While flexible, natural language lacks the structure and precision required for complex, long-horizon synthesis. This limitation appears in two key areas: (1) \textbf{Unstructured Repository Design}. Building realistic codebases requires planning across hundreds of files and modules. Natural language cannot reliably encode such large-scale designs. Concise descriptions often omit critical structural details, whereas verbose ones remain ambiguous and difficult to manage. Without a persistent structure, global plans become fragmented and hard to evolve.
% (2) \textbf{Incoherent Implementation Flow}. Realizing a full repository demands tracking generation targets, sequencing execution, and resolving dependencies. Natural language offers no mechanism for maintaining procedural state, causing agents to lose context over time. This results in disjointed behaviors, unresolved links, and brittle implementations.


% To address these limitations, we introduce the Feature Graph, a persistent and evolvable representation that models repository functionality through structured nodes and edges encoding hierarchy, semantics, and data flow. Unlike ambiguous natural language plans, it provides a compact and interpretable medium for reasoning. Building on this representation, we present \ours{}, a graph-driven framework for controllable repository synthesis. It consists of three modular stages that correspond to core dimensions of software development: (1) \textbf{Feature Graph Construction}: Relevant capabilities are selected from a predefined ontology and organized into a task-specific Feature Graph, capturing high-level intent in a hierarchical and modular form. (2) \textbf{Code Structure Concretization}: The graph's hierarchical layout is concretized into a typed code skeleton, including directories, files, and a Data Flow Graph that defines interfaces and dependencies. (3) \textbf{Graph-Guided Code Generation}: Code is generated in topological order based on the graph, with the graph-to-code mapping providing stable context for consistent reasoning and structured implementation.


% We evaluate \ours\ on RepoCraft, a new benchmark designed for repository-level code generation from natural language. Our method achieves up to 85.4\% functionality coverage, produces over 22k lines of code, and supports 43.1\% real-world task success rate, significantly surpassing all baselines across completeness, scale, and correctness. Ablation studies (Section \ref{sec:ablation}) further demonstrate that increasing the size of the Feature Graph leads to proportionally larger and more functional repositories, indicating that our structured representation supports scalable and robust synthesis as project complexity grows.

% \begin{enumerate}
% \item We propose the Feature Graph, a persistent and structured representation that models repository functionality through hierarchical, semantic, and data-flow relationships.
% \item We develop ZeroRepo, a graph-driven synthesis framework that systematically transforms Feature Graphs into executable codebases with minimal human intervention.
% \item We construct the RepoCraft benchmark to evaluate repository-scale code generation, and show that our structured representation enables high coverage, accuracy, and scalability as project complexity grows.
% \end{enumerate}

% The intrinsic difficulty arises from real projects spanning numerous modules, interfaces, and dependencies, whose scale and coupling quickly exceed the capacity of single step generation. Current approaches fall into three broad camps: multiagent coordination~\cite{hong2023metagpt, qian2023chatdev}, fixed workflows~\cite{seo2025paper2code, lin2025autop2c}, and general purpose agent frameworks~\cite{wang2024openhands, openai_codex_2025, anthropic2025claudecode, google_gemini_cli_2025}. Despite this methodological variety, the repositories these systems produce remain small, shallow in structure, and far from the complexity of production grade software.

% Recent large language models (LLMs) have shown strong performance on relatively simple programming tasks such as generating individual functions or files~\cite{zhu2024deepseek, wang2025epicoder, liu2025rstar, zeng2025acecoder}. Building on this progress, the research community is now turning its attention toward significantly more complex and general scenarios, such as full repository synthesis, where an agent autonomously constructs a complete, coherent, and executable codebase.



% Unlike simplified coding tasks, repository-level generation requires complex reasoning across multiple levels of abstraction, including module interactions, API consistency, and architectural coherence. One of the central challenges lies in forming and maintaining a coherent plan that connects high-level user intent with low-level implementation details. This reasoning spans two intertwined dimensions: (1) \textbf{repository-level planning}, which defines the overall structure, including the skeleton, key components, and their responsibilities; (2) \textbf{execution-level planning}, which governs how the system is incrementally constructed, including implementation order, coding decisions, and iterative debugging. To support such reasoning, researchers have proposed three distinct paradigms. Multi-agent coordination~\cite{hong2023metagpt, qian2023chatdev} distributes reasoning across multiple specialized agents that communicate under predefined Standard Operating Procedures (SOPs). Fixed workflows~\cite{seo2025paper2code, lin2025autop2c} embed reasoning within static pipelines that convert structured inputs into sequential implementation steps. General-purpose agent frameworks~\cite{wang2024openhands, openai_codex_2025, anthropic2025claudecode, google_gemini_cli_2025} externalize reasoning through markdown-based scratchpads and iterative tool usage to drive progress. 


% We argue that using natural language as the primary medium for planning and reasoning introduces two fundamental limitations in repository-level code generation: (1) High-entropy design representation. Natural language lacks formal structure and granularity control, making it difficult to express precise and modular repository plans. Task boundaries are often implicit or overlapping, and critical design information is frequently ambiguous or omitted. Consequently, the resulting architectures are brittle, shallow, and difficult to validate. (2) Unstable implementation grounding. Natural language does not align well with executable semantics. In multi-step workflows involving hundreds or thousands of interdependent components, linguistic ambiguity leads to semantic drift and error accumulation. This results in fragile implementations that struggle to scale to complex, real-world systems.


% We argue that the limitations of current approaches fall into two primary dimensions:
% (1) \textbf{High-entropy repository design}. Transforming user requirements into a complete repository design requires knowledge augmentation and structured planning. However, existing methods rely on natural language, which is inherently high-entropy and ambiguous. This often leads to information loss, imprecise task boundaries, and, in some cases, brittle and shallow architectures. Additionally, the ambiguity of natural language results in fuzzy task boundaries, requiring multiple interactions for disambiguation.
% (2) \textbf{Unstable repository implementation}. Once a plan is established, the agent must translate it into executable code. Natural language reasoning further compounds information loss and struggles with the long-horizon nature of repository construction, which involves hundreds or thousands of dependent steps. This leads to fragile, error-prone implementations that are difficult to scale to large, real-world systems. Both limitations stem from the high-entropy and ambiguous nature of natural language representation and current planning methods.



% Large Language Models (LLMs) have shown impressive progress in software engineering, advancing from function-level generation to full repository synthesis. Recent efforts push toward agent-driven codebase construction, but consistently fail at real-world scale—producing architectures that are shallow, brittle, and unmaintainable. These failures reflect not implementation flaws, but a deeper misalignment with foundational software engineering principles.

% We argue that the failure of current methods stems from three fundamental limitations. (1) \textbf{Static, Single-turn Planning}: Architectural designs are produced through single-turn decisions by LLMs (e.g., UML diagrams), making them unstable and difficult to adapt as requirements evolve. (2) \textbf{Uncontrolled Long-Context Generation}: These approaches rely entirely on LLMs to reason across long prompt chains without intermediate structure or procedural control, resulting in a flat, unmanaged process where early errors propagate unchecked and are hard to revise. (3) \textbf{Generation Without Verification}: These methods lack the testing infrastructure common in real-world software development, such as automated unit, integration, and regression checks, leaving the generated code unverifiable and fundamentally unreliable for complex systems.

% To address these limitations, we introduce the Feature Graph, a persistent and evolvable representation that encodes repository functionalities along with their hierarchical and data-flow dependencies. Unlike high-entropy natural language plans, the Feature Graph serves as a dynamic architectural blueprint that adapts to evolving requirements and provides a stable foundation for the entire development process. This representation removes the redundancy and ambiguity inherent in natural language, retaining only key semantic and syntactic information. Each node and edge in the graph is structured, and verifiable, ensuring precision in both design and execution. Building on this representation, we develop \ours, a graph-driven framework for controllable repository synthesis. The workflow consists of three modular stages: (1) \textbf{Feature Graph Construction}: selecting relevant capabilities from a large ontology and organizing them into cohesive, decoupled subgraphs; (2) \textbf{Code Structure Mapping}: translating the graph into a typed code skeleton with directories, files, classes, and an explicit Data Flow Graph (DFG) to formalize inter-module interfaces; (3) \textbf{Graph-Guided Synthesis}: generating code in topological order and embedding unit, integration, and regression tests to ensure correctness and maintainability.

% We evaluate \ours\ by generating a Python machine-learning library from a high-level description of \textsc{Scikit-Learn}. The resulting repository matches the original’s depth and cleanly adds new components such as visualization and advanced optimizers.

% Our contributions are as follows:
% \begin{enumerate}
% \item We introduce \ours, the first framework to use a persistent Feature Graph to decouple architectural planning from code generation.
% \item We present a graph-guided synthesis pipeline that combines localization-editing with a multi-level testing harness (unit, regression, integration) and majority-vote diagnosis, delivering continuous, automated verification.
% \item Our experiment demonstrates that \ours\ can build a Scikit-Learn–scale repository from scratch, achieving coherent structure and extensible functionality without manual intervention.
% \end{enumerate}



