docs — examples

docs — examples

This document provides developer-focused documentation for the docs/examples/tool-usage.md module within the Code Buddy project.

Module Overview

The docs/examples/tool-usage.md file serves as a comprehensive guide and reference for users interacting with Code Buddy's various capabilities. It is a static Markdown document that showcases practical examples of how to invoke and combine Code Buddy's internal tools and commands.

Unlike executable code modules, this file does not contain any runtime logic, functions, or classes. Its sole purpose is to provide clear, actionable examples that demonstrate the breadth and depth of Code Buddy's interactive features, helping users understand how to formulate effective prompts.

Purpose and Audience

The primary purpose of tool-usage.md is to:

1. Educate Users: Provide concrete examples for each available tool, illustrating basic and advanced usage patterns.
2. Inspire Complex Workflows: Demonstrate how individual tools can be combined into multi-step instructions for complex tasks like refactoring, feature addition, or debugging.
3. Promote Best Practices: Guide users on how to write effective, specific, and contextual prompts for optimal results.
4. Document Capabilities: Serve as a living reference for the full range of operations Code Buddy can perform.

The target audience for this documentation is primarily Code Buddy end-users who want to leverage the system effectively. For developers contributing to Code Buddy, this module is important as it represents the user-facing documentation of the tools they implement. Any changes to tool functionality or the introduction of new tools should be reflected here.

Content Structure

The tool-usage.md file is structured logically to introduce tools by category, then progress to more advanced concepts like multi-step workflows and best practices.

1. Tool Categories

The document begins by categorizing Code Buddy's core tools, providing examples for each:

• File Operations: Demonstrates commands for interacting with the local filesystem.
• read_file: Reading file contents.
• write_file: Creating or overwriting files.
• edit_file: Making targeted modifications to existing files.
• list_directory: Browsing directory contents.
• Search Operations: Covers tools for finding files and content.
• glob: Finding files by pattern.
• grep: Searching file contents.
• Shell Operations: Illustrates how to execute arbitrary shell commands.
• bash: Running shell commands (e.g., npm install, git status).
• Web Operations: Examples for interacting with web resources.
• web_search: Performing internet searches.
• web_fetch: Fetching content from URLs.

Each tool section includes multiple example prompts, showcasing different use cases and parameters (e.g., line ranges for read_file, recursive listing for list_directory).

2. Advanced Examples

This section moves beyond individual tool usage to demonstrate how Code Buddy can handle more complex, high-level instructions:

• Multi-Step Workflows: Examples of breaking down large tasks (e.g., "Refactoring a module," "Adding a new feature," "Debugging an issue") into sequential steps that Code Buddy can execute.
• Project Analysis: Demonstrates prompts for higher-level tasks like "Codebase overview," "Security audit," and "Performance review."

3. Tool Combinations

This section explicitly highlights how different categories of tools can be combined within a single prompt to achieve powerful outcomes:

• Reading + Editing
• Search + Edit
• Bash + File Operations
• Web + Code

4. Error Handling Examples

Examples are provided to show how users can instruct Code Buddy to handle potential failures or require confirmations for destructive operations. This includes:

• Conditional actions based on operation success/failure.
• Demonstrating default confirmation prompts for operations like file deletion or system commands.

5. Best Practices

The document concludes with guidelines for writing effective prompts:

• Be Specific: Emphasizing detailed instructions over vague ones.
• Provide Context: Encouraging users to include relevant project context.
• Break Down Complex Tasks: Advising on structuring large problems into smaller, manageable steps.
• Review Before Confirming: Recommending the use of buddy --mode plan for major changes.

Contribution Guidelines

As a developer, contributing to docs/examples/tool-usage.md is crucial for keeping the user documentation accurate and comprehensive.

When to Contribute

• New Tool Introduction: When a new tool is added to Code Buddy, it should be documented here with examples.
• Tool Feature Updates: If an existing tool gains new capabilities or parameters, update its examples.
• Improved Workflows: If new, effective ways of combining tools or structuring prompts are discovered, add them.
• Clarity and Accuracy: If existing examples are unclear, incorrect, or could be improved, submit a change.

How to Contribute

1. Locate the Relevant Section: Find the appropriate tool category or create a new one if a new tool is being introduced.
2. Add Examples:

• Each example should start with > followed by the prompt.
• Use clear, concise language.
• Focus on demonstrating a specific aspect or use case of the tool.
• Include comments (#) to explain the purpose of the example if necessary.
• Ensure examples are realistic and actionable within a typical development environment.

1. Maintain Markdown Formatting: Adhere to standard Markdown syntax for headings, code blocks, and lists.
2. Review for Clarity: Read through your additions as if you were a new user. Is it easy to understand? Does it clearly demonstrate the intended functionality?
3. Test Examples (Mentally): While not executable, mentally walk through what Code Buddy would do with your example prompt to ensure it makes sense and would yield a useful outcome.

Example Structure for a New Tool

### new_tool_name

Brief description of what `new_tool_name` does:

Basic usage

Use new_tool_name to do X

With specific option

Use new_tool_name with --option to do Y

Error case / edge case

Try new_tool_name on Z, expecting A

```

Relationship to the Codebase

docs/examples/tool-usage.md is a static asset. It has no direct execution flow or dependencies on other code modules. Its content is consumed by the Code Buddy user interface or documentation system to present usage examples to the end-user.

There are no internal calls, outgoing calls, incoming calls, or detected execution flows for this module, as it is purely a documentation file. Therefore, a Mermaid diagram would not add value in explaining its architecture or interactions.