PROMPT_ENGINEERING_BEST_PRACTICES_GUIDE

🏠 Home
Home / DOCS

Prompt Engineering Best Practices Guide

Executive Summary

The most effective techniques for generating production-ready code from Agentic Code Editors hinge on a systematic approach that combines detailed context provisioning, structured reasoning, and iterative refinement. Proven strategies from 2024-2025 demonstrate a clear shift from simple, single-shot prompts to sophisticated, multi-turn agentic workflows. By treating the AI as a junior developer that requires clear, comprehensive instructions and a well-defined environment, developers can consistently produce high-quality, maintainable code while minimizing rework and debugging cycles.

Top 10 Proven Techniques for Agentic Code Editors

These techniques are ranked by their empirical effectiveness, high adoption in successful projects, and consistency across various coding tasks, with a focus on ease of implementation.

Rank Technique Classification Summary
1 Context Engineering with Project-Specific Files Context Optimization Creating dedicated files (like CLAUDE.md) that provide persistent, high-level context about the project's architecture, tools, and coding conventions. This is the single most effective technique for ensuring the AI adheres to project standards.
2 Structured Chain-of-Thought (SCoT) Prompting Advanced Strategies Forcing the AI to first break down a problem into logical steps that mirror programming structures (sequence, branch, loop) before writing code. This significantly improves logical correctness and has been shown to outperform standard Chain-of-Thought by up to 13.79% in Pass@1 accuracy.
3 Iterative Refinement & Self-Correction Quality Assurance Treating code generation as a loop, not a single event. This involves generating code, immediately asking the AI to critique its own output for bugs or improvements, and then refining it based on that feedback.
4 Test-Driven Development (TDD) with AI Quality Assurance Providing the AI with a set of unit tests or a test file first, and then instructing it to write the implementation code required to make all tests pass. This ensures the generated code meets a clear, verifiable target.
5 Few-Shot Example-Based Prompting Foundation Techniques Including 2-3 high-quality examples of the desired code style, format, or logic directly within the prompt. This is highly effective for enforcing coding standards and ensuring stylistic consistency.
6 Meta-Prompting for Task Decomposition Advanced Strategies Using a "prompt to create a prompt." This involves first asking the AI to break down a complex feature request into a detailed checklist or a series of smaller, actionable prompts, which are then executed sequentially.
7 Explicit Context Provisioning (File & Snippet Inclusion) Context Optimization Manually including relevant code snippets, file contents, and directory structures directly in the prompt. Modern editors facilitate this, and it's crucial for tasks that require modifying existing code.
8 Persona-Based Prompting with Role Assignment Foundation Techniques Assigning the AI a specific role, such as "You are a senior Python developer specializing in secure and readable code." This primes the model to generate output that aligns with the expertise and best practices of that role.
9 Multi-Agent Workflows Advanced Strategies Using multiple AI instances for different, specialized tasks. For example, one agent acts as the "Implementer" to write code, while a second "Tester" agent writes unit tests for the generated code, and a third "Reviewer" agent checks for bugs and style violations.
10 Progressive Disclosure of Requirements Advanced Strategies For large or complex features, instead of providing all requirements at once, developers should provide an initial high-level goal and then add constraints and details progressively over several turns. This mimics a natural development conversation and avoids overwhelming the model.

Implementation Guide

1. Context Engineering with Project-Specific Files

```markdown # Project Context for MyWebApp

## Commands

## Tech Stack

## Coding Conventions

2. Structured Chain-of-Thought (SCoT) Prompting

```` You will write a Python function to filter active users.

First, think step-by-step using the following program structures: 1. Sequence: Define the function signature. 2. Loop: Iterate through each user in the input list. 3. Branch: Inside the loop, check if a user's 'status' attribute is 'active'. 4. Sequence: If active, add the user to a new list. 5. Sequence: After the loop, return the new list of active users.

Now, based on these steps, write the Python code. ```- Use Cases: Algorithm implementation, complex data transformations, and any task requiring non-trivial logic. ````

3. Iterative Refinement & Self-Correction

4. Test-Driven Development (TDD) with AI

``` Here is a set of Pytest tests in a file namedtest_calculator.py`:

```python import pytest from calculator import add

def test_add_positive_numbers(): assert add(2, 3) == 5

def test_add_negative_numbers(): assert add(-2, -3) == -5

def test_add_mixed_numbers(): assert add(5, -3) == 2 ````

Now, create the calculator.py file with the add function implementation that makes all of these tests pass.

```

```

5. Few-Shot Example-Based Prompting

```` I need a TypeScript function to call an API. I will provide the function name and endpoint, and you will generate the code.

# Example 1 ## Input: Function Name: getUser Endpoint: /users/{userId}

## Output: ``typescript /** * Fetches a user by their ID. * @param userId - The ID of the user to fetch. */ export const getUser = async (userId: string): Promise<User> => { const response = await apiClient.get(/users/${userId}`); return response.data; }; ````

# Example 2

## Input:

Function Name: getPosts Endpoint: /posts

## Output:

typescript /** * Fetches all posts. */ export const getPosts = async (): Promise<Post[]> => { const response = await apiClient.get(`/posts`); return response.data; };

Now, generate the code for the following:

## Input:

Function Name: updatePost Endpoint: /posts/{postId}

```

```

Real-World Examples & Templates

```` I need to refactor a piece of legacy code. Your role is a senior software engineer focused on modernization and best practices.

Context: - The current language is [e.g., legacy PHP 5.6]. - The target is [e.g., modern PHP 8.2 with strict types]. - The code connects to a [e.g., MySQL] database.

Files for Context:

The Legacy Code to Refactor: ```php // [Paste the legacy function here] ````

Refactoring Requirements:

  1. Convert the function to a method within a User class.
  2. Replace the raw mysql_query calls with prepared statements using PDO.
  3. Add explicit type hints for all parameters and return values.
  4. Implement proper error handling using a try-catch block.
  5. Ensure the new code is secure against SQL injection.

First, provide a step-by-step plan for the refactoring. Then, provide the complete, refactored code.

```

```

Anti-Patterns to Avoid

  1. Vague & Underspecified Prompts: "Make a chat app." This gives the AI too much room to make poor assumptions about the tech stack, features, and architecture.
  2. Overloading a Single Prompt: "Build a full-stack e-commerce site with user auth, a product catalog, a shopping cart, Stripe integration, and an admin dashboard." This overwhelms the model and leads to incomplete or jumbled code. Break it down into smaller, feature-specific prompts.
  3. Ignoring the Existing Codebase: Prompting for new features without providing any context from the current project files. This results in code that is stylistically inconsistent and doesn't integrate properly.
  4. Trusting without Verifying: Directly committing AI-generated code to production without thorough review and testing. AI models can hallucinate variable names, use deprecated libraries, or introduce subtle security flaws.
  5. Not Specifying Constraints: Failing to mention important constraints like "use this specific library version," "do not make external API calls," or "the function must have a time complexity of O(n log n)." This leads to suboptimal or incorrect solutions.

Source Attribution

This synthesis is based on best practices and research from the following sources, reflecting the state of agentic AI development in 2024-2025.

Gemini CLI Playbook

This playbook will serve as our collection of proven, high-leverage strategies. We will continually append lessons learned as we use Gemini CLI, discovering what makes it tick and what doesn’t. This playbook is a work in progress and should always be kept up to date.

Playbook Entry #1: The Thematic Feature Catalog

1. Objective

This playbook entry automates the project planning phase. It addresses the challenge of manually creating a detailed and logically-ordered feature list, which is often a tedious prerequisite for TDD. The goal is to use a specialized AI persona to analyze high-level project artifacts (like mockups or summaries) and automatically generate a comprehensive, thematically-batched, and correctly-ordered feature plan. This elevates the developer's role from Feature Writer to Project Visionary.

2. Core Principles Used

This workflow is a direct application of several advanced techniques from the guide:

3. The Workflow: From Idea to Actionable Plan

This workflow consists of a single, powerful command that transforms raw ideas into a structured specification.

Phase 1: The Cataloging Command (Your Primary Input)

Your only task is to provide the raw materials and invoke the planner.

`` You are a Lead Technical Planner & Feature Cataloger, as defined incataloguer.md`.

Your task is to analyze the provided application context and generate a complete, thematically-sorted implementation plan in JSON format.

Application Context: @STATIC_MOCKUP.html @app_summary.md

Now, create the file themed_features.json based on your analysis and the core directives of your persona. ```

Phase 2: The AI-Generated Plan (The Artifact)

The AI will not write code or tests. It will produce a single file, themed_features.json, which contains every feature, interaction, and behavior, neatly organized into the three core themes in the correct implementation order. This file is the official "blueprint" for the application. The output of this playbook entry serves as the direct input for Playbook Entry #3.

Playbook Entry #2: The AI-Generated Test Contract

1. Objective

This is the evolution of our original TDD workflow. Its objective is to take the AI-generated themed_features.json blueprint and translate it into a complete, multi-file test suite that acts as a verifiable contract for the entire application. This eliminates the human bottleneck of writing tests and moves the developer's role from Test Architect to Plan Approver.

2. Core Principles Used

This workflow now explicitly chains multiple techniques together:

3. The New Workflow: From Plan to Passing Tests

The process now uses the structured plan to generate tests in batches.

Phase 1: Define the Test Contract (From the AI's Plan)

Your job is to command the AI to turn its own plan into test code.

``` You are a senior test engineer with expertise in Pytest and Playwright.

Your task is to create a complete and robust test suite based on the attached thematic feature plan.

Thematic Feature Plan: @themed_features.json

Your Test Suite Must: 1. Create a separate test file for each theme in the plan (e.g., test_batch_01_ui.py, test_batch_02_logic.py). 2. For each feature within a theme, create a corresponding test_ function. 3. Use Playwright locators and assertions to validate the "trigger," "behavior," and "feedback" for each feature.

Now, using your tools, create the complete test suite. ```

Phase 2: The Thematic Implementation Command

This phase remains the same as our previous discussions. You give the AI one of the new test files (e.g., @tests/test_batch_01_ui.py) and instruct it to write the code to make that specific batch of tests pass. This focused approach is what prevents the model from being overwhelmed.

4. The Evaluation Tool: The Agentic Quality Rubric

To objectively measure the success of any workflow, we use this rubric. A successful run should score high, particularly on the "Rework Required" axis.

Generated on 2025-08-30 08:39:13