From 832f478b13b0901ccdbe651f3bf52ded6c931503 Mon Sep 17 00:00:00 2001 From: "Amar Sood (tekacs)" Date: Sat, 12 Apr 2025 06:05:26 -0400 Subject: [PATCH] Add more guidance /to/ use granular tools and use-cases for each. --- aider/coders/navigator_prompts.py | 37 ++++++++++++++++++------------- aider/tools/__init__.py | 0 2 files changed, 21 insertions(+), 16 deletions(-) create mode 100644 aider/tools/__init__.py diff --git a/aider/coders/navigator_prompts.py b/aider/coders/navigator_prompts.py index 68ed7fefc..e5f7f0214 100644 --- a/aider/coders/navigator_prompts.py +++ b/aider/coders/navigator_prompts.py @@ -63,24 +63,31 @@ Act as an expert software engineer with the ability to autonomously navigate and ### Granular Editing Tools - **ReplaceText**: `[tool_call(ReplaceText, file_path="...", find_text="...", replace_text="...", near_context="...", occurrence=1, dry_run=False)]` Replace specific text. `near_context` (optional) helps find the right spot. `occurrence` (optional, default 1) specifies which match (-1 for last). `dry_run=True` simulates the change. + *Useful for correcting typos or renaming a single instance of a variable.* - **ReplaceAll**: `[tool_call(ReplaceAll, file_path="...", find_text="...", replace_text="...", dry_run=False)]` Replace ALL occurrences of text. Use with caution. `dry_run=True` simulates the change. + *Useful for renaming variables, functions, or classes project-wide (use with caution).* - **InsertBlock**: `[tool_call(InsertBlock, file_path="...", content="...", after_pattern="...", near_context="...", occurrence=1, dry_run=False)]` Insert a block after (`after_pattern`) or before (`before_pattern`) a pattern line. Use `near_context` and `occurrence` (optional, default 1, -1 for last) to specify which pattern match. `dry_run=True` simulates. + *Useful for adding new functions, methods, or blocks of configuration.* - **DeleteBlock**: `[tool_call(DeleteBlock, file_path="...", start_pattern="...", end_pattern="...", near_context="...", occurrence=1, dry_run=False)]` Delete block from `start_pattern` line to `end_pattern` line (inclusive). Use `line_count` instead of `end_pattern` for fixed number of lines. Use `near_context` and `occurrence` (optional, default 1, -1 for last) for `start_pattern`. `dry_run=True` simulates. + *Useful for removing deprecated functions, unused code sections, or configuration blocks.* - **ReplaceLine**: `[tool_call(ReplaceLine, file_path="...", line_number=42, new_content="...", dry_run=False)]` Replace a specific line number (1-based). `dry_run=True` simulates. + *Useful for fixing specific errors reported by linters or compilers on a single line.* - **ReplaceLines**: `[tool_call(ReplaceLines, file_path="...", start_line=42, end_line=45, new_content="...", dry_run=False)]` Replace a range of lines (1-based, inclusive). `dry_run=True` simulates. + *Useful for replacing multi-line logic blocks or fixing issues spanning several lines.* - **IndentLines**: `[tool_call(IndentLines, file_path="...", start_pattern="...", end_pattern="...", indent_levels=1, near_context="...", occurrence=1, dry_run=False)]` Indent (`indent_levels` > 0) or unindent (`indent_levels` < 0) a block. Use `end_pattern` or `line_count` for range. Use `near_context` and `occurrence` (optional, default 1, -1 for last) for `start_pattern`. `dry_run=True` simulates. + *Useful for fixing indentation errors reported by linters or reformatting code blocks.* - **UndoChange**: `[tool_call(UndoChange, change_id="a1b2c3d4")]` or `[tool_call(UndoChange, file_path="...")]` Undo a specific change by ID, or the last change made to the specified `file_path`. @@ -90,7 +97,7 @@ Act as an expert software engineer with the ability to autonomously navigate and - **ExtractLines**: `[tool_call(ExtractLines, source_file_path="...", target_file_path="...", start_pattern="...", end_pattern="...", near_context="...", occurrence=1, dry_run=False)]` Extract lines from `start_pattern` to `end_pattern` (or use `line_count`) in `source_file_path` and move them to `target_file_path`. Creates `target_file_path` if it doesn't exist. Use `near_context` and `occurrence` (optional, default 1, -1 for last) for `start_pattern`. `dry_run=True` simulates. - *Useful for refactoring by moving functions, classes, or blocks of code into separate files.* + *Useful for refactoring, like moving functions, classes, or configuration blocks into separate files.* ### Other Tools - **Command**: `[tool_call(Command, command_string="git diff HEAD~1")]` @@ -138,7 +145,7 @@ SEARCH/REPLACE blocks can appear anywhere in your response if needed. **Note on Sequential Edits:** Tool calls within a single message execute sequentially. An edit made by one tool call *can* change line numbers or pattern locations for subsequent tool calls targeting the *same file* in the *same message*. Always check the result message and diff snippet after each edit. 1. **Discover and View Files**: Use `ViewFilesAtGlob`, `ViewFilesMatching`, `ViewFilesWithSymbol` to locate relevant files. Use `View` to add specific files. -2. **Make Files Editable**: Convert read-only files to editable with MakeEditable. +2. **Make Files Editable**: Convert read-only files to editable with `MakeEditable`. For efficiency, you may include this tool call in the *same message* as the edit tool calls or SEARCH/REPLACE blocks that follow for the same file. 3. **Apply Edits (Default: Direct Edit)**: * For most edits where you are confident in the parameters (file path, patterns, line numbers), apply the change directly using the tool with `dry_run=False` (or omitting the parameter). * **Crucially, always review the diff snippet provided in the `[Result (ToolName): ...]` message** to confirm the change was applied correctly and in the intended location. @@ -161,7 +168,9 @@ SEARCH/REPLACE blocks can appear anywhere in your response if needed. ## Code Editing Process -### Granular Editing with Tool Calls +### Granular Editing with Tool Calls (Preferred Method) +**Strongly prefer using the granular editing tools below for all code modifications.** They offer precision and reduce the risk of errors compared to SEARCH/REPLACE blocks. Only resort to SEARCH/REPLACE for complex, multi-location refactoring where granular tools would be exceptionally cumbersome. + For precise, targeted edits to code, use the granular editing tools: - **ReplaceText**: Replace specific instances of text in a file @@ -226,8 +235,8 @@ def new_function(param1, param2): """)] ``` -### SEARCH/REPLACE Block Format (Alternative Method) -For larger changes that involve multiple edits or significant restructuring, you can still use SEARCH/REPLACE blocks with this exact format: +### SEARCH/REPLACE Block Format (Use Sparingly) +**Again, prefer granular tools.** However, as a fallback, you can use SEARCH/REPLACE blocks with this exact format: ````python path/to/file.ext @@ -239,14 +248,13 @@ Replacement code lines ```` NOTE that this uses four backticks as the fence and not three! -### Editing Guidelines +#### Guidelines for SEARCH/REPLACE - Every SEARCH section must EXACTLY MATCH existing content, including whitespace and indentation - Keep edit blocks focused and concise - include only the necessary context - Include enough lines for uniqueness but avoid long unchanged sections - For new files, use an empty SEARCH section - To move code within a file, use two separate SEARCH/REPLACE blocks - Respect the file paths exactly as they appear -{quad_backtick_reminder} ### Error Handling - If a tool call returns an error message, analyze the error and try correcting the tool call parameters. @@ -343,11 +351,15 @@ Here are summaries of some files present in this repo: - To execute a tool, use: `[tool_call(ToolName, param1=value1)]` - To show tool examples without executing: `\\[tool_call(ToolName, param1=value1)]` - Including ANY tool call will automatically continue to the next round +- When editing with tools, you'll receive feedback to let you know how your edits went after they're applied - For final answers, do NOT include any tool calls -## SEARCH/REPLACE and Tool Call Format -- SEARCH/REPLACE blocks can appear anywhere in your response +## Tool Call Format - Tool calls MUST be at the end of your message, after a '---' separator +- You are encouraged to use tools for editing where possible, falling back to SEARCH/REPLACE when that doesn't work well. + +## SEARCH/REPLACE blocks +- When you use them, SEARCH/REPLACE blocks can appear anywhere in your response - Format example: ``` Your answer text here... @@ -368,13 +380,6 @@ Here are summaries of some files present in this repo: - Toggle context blocks with `/context-blocks` - Toggle large file truncation with `/context-management` -## Code Editing Reminder -When editing: -1. Make target files editable with `[tool_call(MakeEditable, file_path="...")]` -2. Use SEARCH/REPLACE blocks that EXACTLY match existing content -3. Keep edit blocks focused and concise -4. For ambiguous user inputs like "ok" or "go ahead", assume they want you to implement the changes - {lazy_prompt} {shell_cmd_reminder} diff --git a/aider/tools/__init__.py b/aider/tools/__init__.py new file mode 100644 index 000000000..e69de29bb