|
| 1 | +--- |
| 2 | +description: You are an expert at using C++ language service tools (GetSymbolReferences_CppTools, GetSymbolInfo_CppTools, GetSymbolCallHierarchy_CppTools). Instructions for calling C++ Tools for Copilot. When working with C++ code, you have access to powerful language service tools that provide accurate, IntelliSense-powered analysis. **Always prefer these tools over manual code inspection, text search, or guessing.** |
| 3 | +applyTo: **/*.cpp, **/*.h, **/*.hpp, **/*.cc, **/*.cxx, **/*.c |
| 4 | +--- |
| 5 | +## Available C++ Tools |
| 6 | + |
| 7 | +You have access to three specialized C++ tools: |
| 8 | + |
| 9 | +1. **`GetSymbolInfo_CppTools`** - Find symbol definitions and get type details |
| 10 | +2. **`GetSymbolReferences_CppTools`** - Find ALL references to a symbol |
| 11 | +3. **`GetSymbolCallHierarchy_CppTools`** - Analyze function call relationships |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Mandatory Tool Usage Rules |
| 16 | + |
| 17 | +### Rule 1: ALWAYS Use GetSymbolReferences_CppTools for Symbol Usages |
| 18 | + |
| 19 | +**NEVER** rely on manual code inspection, `vscode_listCodeUsages`, `grep_search`, or `read_file` to find where a symbol is used. |
| 20 | + |
| 21 | +**ALWAYS** call `GetSymbolReferences_CppTools` when: |
| 22 | +- Renaming any symbol (function, variable, class, method, etc.) |
| 23 | +- Changing function signatures |
| 24 | +- Refactoring code |
| 25 | +- Understanding symbol impact |
| 26 | +- Finding all call sites |
| 27 | +- Identifying usage patterns |
| 28 | +- Any task involving "find all uses/usages/references/calls" |
| 29 | + |
| 30 | +**Why**: `GetSymbolReferences_CppTools` uses C++ IntelliSense and understands: |
| 31 | +- Overloaded functions |
| 32 | +- Template instantiations |
| 33 | +- Qualified vs unqualified names |
| 34 | +- Member function calls |
| 35 | +- Inherited member usage |
| 36 | +- Preprocessor-conditional code |
| 37 | + |
| 38 | +Text search tools will miss these or produce false positives. |
| 39 | + |
| 40 | +### Rule 2: ALWAYS Use GetSymbolCallHierarchy_CppTools for Function Changes |
| 41 | + |
| 42 | +Before modifying any function signature, **ALWAYS** call `GetSymbolCallHierarchy_CppTools` with `callsFrom=false` to find all callers. |
| 43 | + |
| 44 | +**Examples**: |
| 45 | +- Adding/removing function parameters |
| 46 | +- Changing parameter types |
| 47 | +- Changing return types |
| 48 | +- Making functions virtual |
| 49 | +- Converting to template functions |
| 50 | + |
| 51 | +**Why**: This ensures you update ALL call sites, not just the ones you can see. |
| 52 | + |
| 53 | +### Rule 3: ALWAYS Use GetSymbolInfo_CppTools to Understand Symbols |
| 54 | + |
| 55 | +Before working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to: |
| 56 | +- Find where a symbol is defined |
| 57 | +- Understand class/struct memory layout |
| 58 | +- Get type information |
| 59 | +- Locate declarations |
| 60 | + |
| 61 | +**NEVER** assume you know what a symbol is without checking. |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Parameter Usage Guidelines |
| 66 | + |
| 67 | +### Symbol Names |
| 68 | +- **ALWAYS REQUIRED**: Provide the symbol name |
| 69 | +- Can be unqualified (`MyFunction`), partially qualified (`MyClass::MyMethod`), or fully qualified (`MyNamespace::MyClass::MyMethod`) |
| 70 | +- If you have a line number, the symbol should match what appears on that line |
| 71 | + |
| 72 | +### File Paths |
| 73 | +- **STRONGLY PREFERRED**: Always provide absolute file paths when available |
| 74 | + - ✅ Good: `C:\Users\Project\src\main.cpp` |
| 75 | + - ❌ Avoid: `src\main.cpp` (requires resolution, may fail) |
| 76 | +- If you have access to a file path, include it |
| 77 | +- If working with user-specified files, use their exact path |
| 78 | + |
| 79 | +### Line Numbers |
| 80 | +- **CRITICAL**: Line numbers are 1-based, NOT 0-based |
| 81 | +- **MANDATORY WORKFLOW** when you need a line number: |
| 82 | + 1. First call `read_file` to search for the symbol |
| 83 | + 2. Locate the symbol in the output |
| 84 | + 3. Note the EXACT line number from the output |
| 85 | + 4. VERIFY the line contains the symbol |
| 86 | + 5. Only then call the C++ tool with that line number |
| 87 | +- **NEVER** guess or estimate line numbers |
| 88 | +- If you don't have a line number, omit it - the tools will find the symbol |
| 89 | + |
| 90 | +### Minimal Information Strategy |
| 91 | +Start with minimal information and add more only if needed: |
| 92 | +1. **First attempt**: Symbol name only |
| 93 | +2. **If ambiguous**: Symbol name + file path |
| 94 | +3. **If still ambiguous**: Symbol name + file path + line number (after using `read_file`) |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Common Workflows |
| 99 | + |
| 100 | +### Renaming a Symbol |
| 101 | + |
| 102 | +``` |
| 103 | +CORRECT workflow: |
| 104 | +1. Call GetSymbolReferences_CppTools with symbol name (and file path if available) |
| 105 | +2. Review ALL references returned |
| 106 | +3. Update symbol at definition location |
| 107 | +4. Update symbol at ALL reference locations |
| 108 | +
|
| 109 | +INCORRECT workflow: |
| 110 | +❌ Using vscode_listCodeUsages or grep_search to find usages |
| 111 | +❌ Manually inspecting a few files |
| 112 | +❌ Assuming you know all the usages |
| 113 | +``` |
| 114 | + |
| 115 | +### Changing a Function Signature |
| 116 | + |
| 117 | +``` |
| 118 | +CORRECT workflow: |
| 119 | +1. Call GetSymbolInfo_CppTools to locate the function definition |
| 120 | +2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers |
| 121 | +3. Call GetSymbolReferences_CppTools to catch any additional references (function pointers, etc.) |
| 122 | +4. Update function definition |
| 123 | +5. Update ALL call sites with new signature |
| 124 | +
|
| 125 | +INCORRECT workflow: |
| 126 | +❌ Changing the function without finding callers |
| 127 | +❌ Only updating visible call sites |
| 128 | +❌ Using text search to find calls |
| 129 | +``` |
| 130 | + |
| 131 | +### Understanding Unfamiliar Code |
| 132 | + |
| 133 | +``` |
| 134 | +CORRECT workflow: |
| 135 | +1. Call GetSymbolInfo_CppTools on key types/functions to understand definitions |
| 136 | +3. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to understand what a function does |
| 137 | +4. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to understand where a function is used |
| 138 | +
|
| 139 | +INCORRECT workflow: |
| 140 | +❌ Reading code manually without tool assistance |
| 141 | +❌ Making assumptions about symbol meanings |
| 142 | +❌ Skipping hierarchy analysis |
| 143 | +``` |
| 144 | + |
| 145 | +### Analyzing Function Dependencies |
| 146 | + |
| 147 | +``` |
| 148 | +CORRECT workflow: |
| 149 | +1. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to see what the function calls (outgoing) |
| 150 | +2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to see what calls the function (incoming) |
| 151 | +3. Use this to understand code flow and dependencies |
| 152 | +
|
| 153 | +INCORRECT workflow: |
| 154 | +❌ Manually reading through function body |
| 155 | +❌ Guessing at call patterns |
| 156 | +``` |
| 157 | + |
| 158 | +--- |
| 159 | + |
| 160 | +## Error Handling and Recovery |
| 161 | + |
| 162 | +### When You Get an Error Message |
| 163 | + |
| 164 | +**All error messages contain specific recovery instructions. ALWAYS follow them exactly.** |
| 165 | + |
| 166 | +#### "Symbol name is not valid" Error |
| 167 | +``` |
| 168 | +Error: "The symbol name is not valid: it is either empty or null. Find a valid symbol name. Then call the [tool] tool again" |
| 169 | +
|
| 170 | +Recovery: |
| 171 | +1. Ensure you provided a non-empty symbol name |
| 172 | +2. Check that the symbol name is spelled correctly |
| 173 | +3. Retry with valid symbol name |
| 174 | +``` |
| 175 | + |
| 176 | +#### "File could not be found" Error |
| 177 | +``` |
| 178 | +Error: "A file could not be found at the specified path. Compute the absolute path to the file. Then call the [tool] tool again." |
| 179 | +
|
| 180 | +Recovery: |
| 181 | +1. Convert relative path to absolute path |
| 182 | +2. Verify file exists in the workspace |
| 183 | +3. Use exact path from user or file system |
| 184 | +4. Retry with absolute path |
| 185 | +``` |
| 186 | + |
| 187 | +#### "No results found" Message |
| 188 | +``` |
| 189 | +Message: "No results found for the symbol '[symbol_name]'." |
| 190 | +
|
| 191 | +This is NOT an error - it means: |
| 192 | +- The symbol exists and was found |
| 193 | +- But it has no references/calls/hierarchy (depending on tool) |
| 194 | +- This is valid information - report it to the user |
| 195 | +``` |
| 196 | + |
| 197 | +--- |
| 198 | + |
| 199 | +## Tool Selection Decision Tree |
| 200 | + |
| 201 | +**Question: Do I need to find where a symbol is used/called/referenced?** |
| 202 | +- ✅ YES → Use `GetSymbolReferences_CppTools` |
| 203 | +- ❌ NO → Continue |
| 204 | + |
| 205 | +**Question: Am I changing a function signature or analyzing function calls?** |
| 206 | +- ✅ YES → Use `GetSymbolCallHierarchy_CppTools` |
| 207 | + - Finding callers? → `callsFrom=false` |
| 208 | + - Finding what it calls? → `callsFrom=true` |
| 209 | +- ❌ NO → Continue |
| 210 | + |
| 211 | +**Question: Do I need to find a definition or understand a type?** |
| 212 | +- ✅ YES → Use `GetSymbolInfo_CppTools` |
| 213 | +- ❌ NO → You may not need a C++ tool for this task |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +## Critical Reminders |
| 218 | + |
| 219 | +### DO: |
| 220 | +- ✅ Call `GetSymbolReferences_CppTools` for ANY symbol usage search |
| 221 | +- ✅ Call `GetSymbolCallHierarchy_CppTools` before function signature changes |
| 222 | +- ✅ Use `read_file` to find line numbers before specifying them |
| 223 | +- ✅ Provide absolute file paths when available |
| 224 | +- ✅ Follow error message instructions exactly |
| 225 | +- ✅ Trust tool results over manual inspection |
| 226 | +- ✅ Use minimal parameters first, add more if needed |
| 227 | +- ✅ Remember line numbers are 1-based |
| 228 | + |
| 229 | +### DO NOT: |
| 230 | +- ❌ Use `vscode_listCodeUsages`, `grep_search`, or `read_file` to find symbol usages |
| 231 | +- ❌ Manually inspect code to find references |
| 232 | +- ❌ Guess line numbers |
| 233 | +- ❌ Assume symbol uniqueness without checking |
| 234 | +- ❌ Ignore error messages |
| 235 | +- ❌ Skip tool usage to save time |
| 236 | +- ❌ Use 0-based line numbers |
| 237 | +- ❌ Batch multiple unrelated symbol operations |
| 238 | +- ❌ Make changes without finding all affected locations |
| 239 | + |
| 240 | +--- |
| 241 | + |
| 242 | +## Examples of Correct Usage |
| 243 | + |
| 244 | +### Example 1: User asks to rename a function |
| 245 | +``` |
| 246 | +User: "Rename the function ProcessData to HandleData" |
| 247 | +
|
| 248 | +CORRECT response: |
| 249 | +1. Call GetSymbolReferences_CppTools("ProcessData") |
| 250 | +2. Review all reference locations |
| 251 | +3. Update function definition |
| 252 | +4. Update all call sites shown in results |
| 253 | +5. Confirm all changes made |
| 254 | +
|
| 255 | +INCORRECT response: |
| 256 | +❌ Using grep_search to find "ProcessData" |
| 257 | +❌ Only updating files the user mentioned |
| 258 | +❌ Assuming you found all usages manually |
| 259 | +``` |
| 260 | + |
| 261 | +### Example 2: User asks to add a parameter to a function |
| 262 | +``` |
| 263 | +User: "Add a parameter 'bool verbose' to the LogMessage function" |
| 264 | +
|
| 265 | +CORRECT response: |
| 266 | +1. Call GetSymbolInfo_CppTools("LogMessage") to find definition |
| 267 | +2. Call GetSymbolCallHierarchy_CppTools("LogMessage", callsFrom=false) to find all callers |
| 268 | +3. Call GetSymbolReferences_CppTools("LogMessage") to catch any function pointer uses |
| 269 | +4. Update function definition |
| 270 | +5. Update ALL call sites with new parameter |
| 271 | +
|
| 272 | +INCORRECT response: |
| 273 | +❌ Only updating the definition |
| 274 | +❌ Updating only obvious call sites |
| 275 | +❌ Not using call_hierarchy tool |
| 276 | +``` |
| 277 | + |
| 278 | +### Example 3: User asks to understand a function |
| 279 | +``` |
| 280 | +User: "What does the Initialize function do?" |
| 281 | +
|
| 282 | +CORRECT response: |
| 283 | +1. Call GetSymbolInfo_CppTools("Initialize") to find definition and location |
| 284 | +2. Call GetSymbolCallHierarchy_CppTools("Initialize", callsFrom=true) to see what it calls |
| 285 | +3. Read the function implementation |
| 286 | +4. Explain based on code + call hierarchy |
| 287 | +
|
| 288 | +INCORRECT response: |
| 289 | +❌ Only reading the function body |
| 290 | +❌ Not checking what it calls |
| 291 | +❌ Guessing at behavior |
| 292 | +``` |
| 293 | + |
| 294 | +--- |
| 295 | + |
| 296 | +## Performance and Best Practices |
| 297 | + |
| 298 | +### Efficient Tool Usage |
| 299 | +- Call tools in parallel when analyzing multiple independent symbols |
| 300 | +- Use file paths to speed up symbol resolution |
| 301 | +- Provide context to narrow searches |
| 302 | + |
| 303 | +### Iterative Refinement |
| 304 | +- If first tool call is ambiguous, add file path |
| 305 | +- If still ambiguous, use `read_file` to find exact line |
| 306 | +- Tools are designed for iteration |
| 307 | + |
| 308 | +### Understanding Results |
| 309 | +- **Empty results are valid**: "No results found" means the symbol has no references/calls |
| 310 | +- **Multiple results are common**: C++ has overloading, templates, namespaces |
| 311 | +- **Trust the tools**: IntelliSense knows C++ semantics better than text search |
| 312 | + |
| 313 | +--- |
| 314 | + |
| 315 | +## Integration with Other Tools |
| 316 | + |
| 317 | +### When to use read_file |
| 318 | +- **ONLY** for finding line numbers before calling C++ tools |
| 319 | +- **ONLY** for reading implementation details after locating symbols |
| 320 | +- **NEVER** for finding symbol usages (use `GetSymbolReferences_CppTools` instead) |
| 321 | + |
| 322 | +### When to use vscode_listCodeUsages/grep_search |
| 323 | +- Finding string literals or comments |
| 324 | +- Searching non-C++ files |
| 325 | +- Pattern matching in configuration files |
| 326 | +- **NEVER** for finding C++ symbol usages |
| 327 | + |
| 328 | +### When to use semantic_search |
| 329 | +- Finding code based on conceptual queries |
| 330 | +- Locating relevant files in large codebases |
| 331 | +- Understanding project structure |
| 332 | +- **Then** use C++ tools for precise symbol analysis |
| 333 | + |
| 334 | +--- |
| 335 | + |
| 336 | +## Summary |
| 337 | + |
| 338 | +**The golden rule**: When working with C++ code, think "tool first, manual inspection later." |
| 339 | + |
| 340 | +1. **Symbol usages?** → `GetSymbolReferences_CppTools` |
| 341 | +2. **Function calls?** → `GetSymbolCallHierarchy_CppTools` |
| 342 | +3. **Symbol definition?** → `GetSymbolInfo_CppTools` |
| 343 | + |
| 344 | +These tools are your primary interface to C++ code understanding. Use them liberally and often. They are fast, accurate, and understand C++ semantics that text search cannot capture. |
| 345 | + |
| 346 | +**Your success metric**: Did I use the right C++ tool for every symbol-related task? |
0 commit comments