Commit bcd19cd3 authored by Jan Reimes's avatar Jan Reimes
Browse files

docs: enhance grepai usage guidelines in AGENTS.md 

- Added detailed instructions for using grepai as the primary tool for code exploration.
- Included sections on when to use grepai versus standard tools.
- Provided usage examples and query tips for better semantic matching.
- Introduced call graph tracing commands for understanding function relationships.
parent 3a453305

AGENTS.md

+71 −0
Original line number Diff line number Diff line
@@ -15,6 +15,77 @@ Before implementing features, review these critical sections: 
- `src/tdoc_crawler/crawlers/*.py` - Crawler implementations

- `tests/conftest.py` - Shared test fixtures



## grepai - Semantic Code Search



**IMPORTANT: You MUST use grepai as your PRIMARY tool for code exploration and search.**



### When to Use grepai (REQUIRED)



Use `grepai search` INSTEAD OF Grep/Glob/find for:



- Understanding what code does or where functionality lives

- Finding implementations by intent (e.g., "authentication logic", "error handling")

- Exploring unfamiliar parts of the codebase

- Any search where you describe WHAT the code does rather than exact text



### When to Use Standard Tools



Only use Grep/Glob when you need:



- Exact text matching (variable names, imports, specific strings)

- File path patterns (e.g., `**/*.go`)



### Fallback



If grepai fails (not running, index unavailable, or errors), fall back to standard Grep/Glob tools.



### Usage



```bash

# ALWAYS use English queries for best results (--compact saves ~80% tokens)

grepai search "user authentication flow" --json --compact

grepai search "error handling middleware" --json --compact

grepai search "database connection pool" --json --compact

grepai search "API request validation" --json --compact

```



### Query Tips



- **Use English** for queries (better semantic matching)

- **Describe intent**, not implementation: "handles user login" not "func Login"

- **Be specific**: "JWT token validation" better than "token"

- Results include: file path, line numbers, relevance score, code preview



### Call Graph Tracing



Use `grepai trace` to understand function relationships:



- Finding all callers of a function before modifying it

- Understanding what functions are called by a given function

- Visualizing the complete call graph around a symbol



#### Trace Commands



**IMPORTANT: Always use `--json` flag for optimal AI agent integration.**



```bash

# Find all functions that call a symbol

grepai trace callers "HandleRequest" --json



# Find all functions called by a symbol

grepai trace callees "ProcessOrder" --json



# Build complete call graph (callers + callees)

grepai trace graph "ValidateToken" --depth 3 --json

```



### Workflow



1. Start with `grepai search` to find relevant code

2. Use `grepai trace` to understand function relationships

3. Use `Read` tool to examine files from results

4. Only use Grep for exact string searches if needed



## Issue Tracking with beads (bd)



This project uses **bd (beads)** for issue tracking.