Semantic Search Query Generation Prompt for Codebases

This prompt is designed for AI coding agents that need to translate a natural language intent—such as 'find where authentication logic checks user roles' or 'locate the database migration that added the email column'—into one or more precise, structured search queries. The primary job-to-be-done is bridging the gap between a developer's high-level question and the literal patterns that grep, ripgrep, or AST-based search tools require. The ideal user is an AI engineer or developer building a coding agent that must autonomously explore an unfamiliar repository, locate relevant code, and assemble context before planning an edit.

Use this prompt when the agent has a clear natural language question about the codebase but lacks the specific function names, file paths, or literal strings needed for an effective search. It is appropriate for initial codebase exploration, bug investigation, feature location, and dependency tracing. The prompt requires the agent's current working directory, available search tools, and the codebase's primary language or framework as context. It should not be used when the agent already knows the exact file and line number, when the task is a simple file read rather than a search, or when the search tool has a strict regex engine that cannot handle the generated alternatives.

Avoid this prompt for real-time, latency-sensitive search loops where the overhead of an LLM call is unacceptable; a cached or heuristic-based query expander is a better fit. It is also unsuitable for searching binary files, generated code, or vendored dependencies unless those directories are explicitly included in the search scope. For high-risk codebases where a missed result could cause a security or compliance incident, always pair this prompt with a post-search validation step that confirms the critical code was found, and escalate to a human operator if the search yields zero results for a safety-sensitive query.

This prompt template is designed to be the core instruction set for an AI coding agent that must convert a developer's natural language question into a precise, structured search query. The template uses square-bracket placeholders for all dynamic inputs, allowing you to wire it directly into an application harness. The goal is to produce queries that are specific enough to avoid flooding the context window with irrelevant results, yet flexible enough to catch semantically related code that a literal grep would miss.

textCopy
You are a code search query generator. Your task is to translate a natural language intent into a set of structured search queries for a codebase exploration tool.

## Input
- **Intent:** [USER_INTENT]
- **Codebase Context:** [CODEBASE_CONTEXT]
- **Available Search Tools:** [AVAILABLE_SEARCH_TOOLS]
- **Output Schema:** [OUTPUT_SCHEMA]

## Instructions
1. Analyze the user's intent to identify the core code entities, relationships, or patterns they are looking for.
2. Generate a primary search query using the most appropriate tool (e.g., `ripgrep` for patterns, `ast-grep` for structural searches).
3. Generate 2-3 alternative queries that use different patterns, synonyms, or tool types to maximize recall. For example, if searching for "error handling in the auth module," generate one query for `try/catch` blocks, another for `auth.*error` function calls, and a third for `throw new.*AuthError`.
4. For each query, assign a relevance score (1-10) based on how directly it addresses the user's intent.
5. If the intent is ambiguous, generate queries for the top 2 most likely interpretations and flag the ambiguity.

## Constraints
- [CONSTRAINTS]
- Do not generate queries that would match more than 500 files unless explicitly requested for a broad scan.
- Prefer queries that target specific directories or file types when the codebase context provides them.
- Exclude common vendor, test fixture, and generated code paths unless the intent suggests otherwise.

## Examples
[EXAMPLES]

## Output Format
Return a valid JSON object conforming to the provided Output Schema.

To adapt this template, start by defining your [OUTPUT_SCHEMA] to enforce a strict structure, such as a JSON object with an array of query objects, each containing query_string, tool_type, target_paths, and relevance_score fields. The [CONSTRAINTS] placeholder should be replaced with project-specific rules, like excluding certain directories or enforcing a maximum file match count. The [EXAMPLES] placeholder is critical for few-shot learning; provide at least two examples that demonstrate how a vague intent maps to a set of precise, alternative queries. After generating the queries, your application harness should validate the JSON structure, check that the tool_type is in the [AVAILABLE_SEARCH_TOOLS] list, and log any queries that exceed your file-match threshold for human review before execution.

This prompt is designed to sit between a natural language interface and a code search backend such as ripgrep, ast-grep, or a language server's symbol search. The agent receives a developer question like "where is authentication logic implemented?" and must produce structured queries that the search tool can execute directly. The prompt is not a standalone chatbot response; it is a query-generation step in a retrieval pipeline. The output should be a JSON array of query objects, each containing a pattern, optional file type filter, and a relevance score, so the harness can iterate through queries in priority order until sufficient results are found or the query budget is exhausted.

Wire this prompt into an agent loop with a configurable max_queries parameter (default 5) and a min_results threshold (default 3). After each query executes, count the results. If results exceed a context-window flood threshold (e.g., 200 matches), append a narrowing constraint to the next query generation call: [PREVIOUS_QUERY] returned too many results. Generate a more specific pattern. If results are zero, append: [PREVIOUS_QUERY] returned no results. Try alternative patterns, synonyms, or broader file scopes. The harness must track which queries have been tried to prevent infinite loops. Log every generated query, the result count, and whether it contributed to the final context bundle for observability and debugging.

For model choice, use a fast, instruction-tuned model such as GPT-4o-mini, Claude Haiku, or a local model like DeepSeek-Coder for latency-sensitive loops. This prompt rarely requires a frontier model because the task is structured pattern generation, not deep reasoning. Implement a timeout of 3 seconds per generation call and a circuit breaker that falls back to a static list of common patterns (e.g., the function name as a literal grep) if the model fails twice. Validate every generated query before execution: reject patterns with unbounded wildcards like .* alone, patterns shorter than 3 characters, or patterns that match the entire codebase (e.g., a single space). If the agent is operating in a regulated or high-risk codebase, log all generated queries for audit and require human approval before executing destructive or modifying operations—though search queries are read-only, the surrounding agent may not be.

The harness should maintain a session-level cache of query-to-result mappings to avoid re-running identical searches within the same task. When the agent assembles final context for the next reasoning step, include the query that found each result so downstream prompts can cite provenance. Avoid wiring this prompt directly to a user-facing chat without the search execution loop; raw query JSON confuses end users and invites manual copy-paste errors. Instead, expose the harness through a tool interface that the coding agent or IDE plugin calls programmatically.