Zicoder's Three-Layer Search Architecture: Code Retrieval Design Practices in Agentic Coding

Why Search Is the Core Capability of Agentic Coding

In the field of AI agentic coding, the quality of search capabilities directly determines the overall system performance. Search fundamentally provides context data for language models—if search results are inaccurate or background information is incomplete, then no matter how good the subsequent code generation is, the direction has already gone astray.

In enterprise applications, RAG (Retrieval-Augmented Generation) has always been a core requirement. RAG is an architectural paradigm that combines external knowledge bases with large language models, proposed by Meta AI in 2020. Its core idea is to retrieve relevant documents from external data sources before the model generates answers, injecting them as context into the prompt to compensate for the model's training data staleness and domain knowledge gaps. In agentic coding scenarios, RAG challenges are far more complex than general Q&A—codebases have strong dependency relationships, symbol references are distributed across files, and semantic understanding requires structural context. This makes single vector retrieval solutions often inadequate. The Zicoder project, designed from a code-centric perspective, implements a complete set of three search methods, each addressing different use cases. This approach offers excellent reference value for understanding search architecture design in agentic coding.

AST-Based Three-Layer Architecture Search: Semantic-Level Code Retrieval

Design Philosophy

The three-layer architecture search is the most complex and powerful search method in Zicoder. It requires project initialization (init) first, scanning the entire codebase and building it into a three-layer structure:

• Requirements Layer: Reverse-engineers business requirements from source code
• Architecture Layer: Extracts system architecture design information
• Implementation Layer: Concrete code implementation details

The core idea behind this design is: questions at different granularities need to be retrieved at different levels. When you ask "how does the system handle user authentication," you need to search at the requirements and architecture layers; when you ask about "the specific implementation of a function," you need to drill down to the implementation layer.

Technical Implementation Details

At the underlying level, the system first performs AST (Abstract Syntax Tree) parsing of the entire codebase, forming a tree structure. AST is the core data structure of the compiler frontend, parsing source code into tree-structured syntax nodes where each node represents a language construct (such as function definitions, variable declarations, conditional statements, etc.). Unlike pure text processing, AST-based analysis can understand the structural semantics of code—for example, distinguishing the meaning of identically-named variables in different scopes, or identifying the hierarchical relationships of function call chains. Modern tools like Tree-sitter support incremental AST parsing for over 40 programming languages and have become standard underlying components for code intelligence tools. After completing AST parsing, the system uses large models to generate semantic descriptions of these nodes, forming a semantic graph, and ultimately supports two levels of retrieval through vectorized storage:

1. Low-level Search: Precise matching based on code structure
2. High-level Semantic Search: Semantic understanding based on natural language

Usage: /codebase query --prompt <search content>. For example, searching for "how to create a command" will return all related code blocks, including function signatures, file locations, and structured description information.

Full-Text Search: Millisecond-Level Positioning via Trigram Inverted Index

Applicable Scenarios

Not all searches require complex semantic understanding. When you simply want to know where a variable or function name is referenced, full-text search is the most efficient choice. This is similar to the global search function in VS Code, but Zicoder encapsulates it as a tool callable by Agents.

Trigram + Inverted Index Approach

Full-text search adopts Google's Trigram + Inverted Index algorithm. Trigram indexing is a text indexing technique that decomposes strings into consecutive three-character segments—for example, the string "hello" is decomposed into the trigrams "hel", "ell", and "llo", while the inverted index records which documents each trigram appears in. During querying, the search term is similarly decomposed into trigrams, and the intersection of document sets corresponding to each trigram is taken to quickly locate candidate documents. Google's code search tool Zoekt and regex search tool Codesearch both employ this approach. The characteristics of this method are:

• No Vectorization Required: Independent of embedding models, entirely memory-based operations
• Pure In-Memory Operations: Millisecond-level response speed, supports regular expressions
• Exact Matching: Suitable for precise positioning of code symbols, an efficient complement to vector retrieval

Usage: /codebase search --dir <search scope> <keyword>. The system performs a full-text scan within the specified directory scope, returning match positions and corresponding function signature definitions.

The advantage of this search method lies in its extreme speed and high result determinism, making it ideal for Agents to quickly locate symbol references during coding.

Agentic Search: Autonomous Exploratory Code Retrieval

Core Concept

Agentic search is the most distinctively "AI agent" search method. Rather than returning results in one shot, it lets an Agent autonomously explore the codebase across multiple rounds, progressively collecting and synthesizing information. Its mechanism is essentially a concrete application of the ReAct (Reasoning + Acting) framework—proposed by Princeton University and Google Brain in 2022, the core idea is to have the language model alternate between reasoning (Thought) and acting (Action): the model first analyzes the current state, decides which tool to call, observes the tool's returned results, and then proceeds to the next round of reasoning.

Usage: /codebase agentic --dir <scope> <search content>.

Working Mechanism

The system provides the search Agent with a series of tools:

• File listing browsing
• File content reading
• grep search
• Directory traversal

The Agent continuously calls these tools in a loop, collecting new information with each iteration. In code exploration scenarios, the Agent might need to first list the directory structure, then read key files, then verify hypotheses through grep, going through multiple iterations to form a complete understanding—this is precisely the capability boundary that static RAG cannot replace. The system records progress at each collection point as "milestones," and ultimately the Agent synthesizes all information to return a complete solution.

Transforming Search Results into Reusable Skills

Agentic search returns not just code snippets, but also:

• Step-by-step operational guides
• Function definitions and call relationships
• Structured knowledge that can be directly converted into Skills

There's an elegant design here: search results can be transformed into reusable skills through the "command to skill" command. This design is essentially an External Memory mechanism—the model's parameter weights represent static trained knowledge, while the Skill library provides dynamic, updatable operational knowledge. Microsoft's Voyager project (an autonomous Agent based on Minecraft) also adopted a similar skill library design, demonstrating the effectiveness of this knowledge accumulation mechanism in complex tasks. For enterprise codebases, this means the Agent becomes increasingly efficient when handling repetitive architectural patterns, truly achieving "search as learning."