code-symbols
Guidance for using Serena's LSP-powered symbol analysis. Use when exploring codebases, finding symbol definitions, tracing references, or when grep/text search would be imprecise.
- License 许可
- MIT
- 最近更新
- 2026-03-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-symbols
- model
- claude-sonnet-4-5
- agents
- [ "analyst" ]
- license
- MIT
- metadata
- { "version": "1.0.0" }
- description
- Guidance for using Serena's LSP-powered symbol analysis. Use when exploring codebases, finding symbol definitions, tracing references, or when grep/text search would be imprecise.
02 资源文件 5
- 许可证LICENSE1.0 KB
- 参考文档references/demo-endpoints.md1.1 KB
- 脚本scripts/coingecko_demo_get.py3.0 KB
- 参考文档SOURCE.md351 B
- 参考文档TRUST.auto.yaml2.1 KB
03 SKILL.md 正文
Code Symbol Analysis
Serena provides LSP-powered code intelligence for accurate symbol extraction, relationship discovery, and cross-file analysis.
When to Use Serena vs Text Search
| Use Serena | Use Grep/Text Search |
|---|---|
| Finding class/function definitions | Searching for string literals |
| Tracing method references | Finding patterns in comments |
| Understanding call hierarchies | Searching config files |
| Analyzing imports/dependencies | Finding TODO/FIXME markers |
| Cross-file architecture analysis | Simple keyword search |
Key advantage: Serena understands code structure. find_symbol("UserService") finds the actual class definition, not every mention of "UserService" in comments or strings.
Core Tools
1. get_symbols_overview
Get high-level view of symbols in a file. Start here when exploring a new file.
mcp__plugin_serena_serena__get_symbols_overview({
"relative_path": "src/services/auth.py",
"depth": 1 # 0=top-level only, 1=include methods
})
Returns: Classes, functions, variables with their kind and location.
2. find_symbol
Find symbols by name pattern. Supports flexible matching.
Name path patterns:
UserService- Find any symbol named "UserService"UserService/authenticate- Find method in class/UserService- Exact match (absolute path)Servicewithsubstring_matching: true- Matches "UserService", "AuthService", etc.
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "UserService/authenticate",
"include_body": true, # Get source code
"depth": 0 # 0=just this symbol, 1=include children
})
Key parameters:
include_body(bool): Include source code (use judiciously for context)depth(int): How many levels of children to retrieverelative_path(str): Restrict search to file/directorysubstring_matching(bool): Partial name matching
3. find_referencing_symbols
Find all references to a symbol. Essential for understanding impact.
mcp__plugin_serena_serena__find_referencing_symbols({
"name_path": "UserService/authenticate",
"relative_path": "src/services/auth.py"
})
Returns: Code snippets showing each reference with context.
4. search_for_pattern
Regex search when you need flexibility (like grep, but smarter file filtering).
mcp__plugin_serena_serena__search_for_pattern({
"substring_pattern": "def.*async.*:",
"restrict_search_to_code_files": true,
"context_lines_before": 2,
"context_lines_after": 2
})
Process
Exploring a New Codebase
-
Directory structure - Understand layout
mcp__plugin_serena_serena__list_dir({ "relative_path": ".", "recursive": false }) -
Entry points - Find main files
mcp__plugin_serena_serena__get_symbols_overview({ "relative_path": "src/main.py", "depth": 1 }) -
Trace key classes - Understand structure
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "App", "include_body": false, "depth": 1 })
Understanding a Specific Class
-
Find the class with children
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService", "depth": 1, "include_body": false }) -
Read specific methods you need
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService/validate_token", "include_body": true }) -
Find who calls it
mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService/validate_token", "relative_path": "src/services/auth.py" })
Tracing Dependencies
-
Find all imports of a module
mcp__plugin_serena_serena__search_for_pattern({ "substring_pattern": "from.*auth.*import|import.*auth", "restrict_search_to_code_files": true }) -
Find references to trace usage
mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService", "relative_path": "src/services/auth.py" })
Symbol Kinds Reference
LSP symbol kinds (for include_kinds/exclude_kinds filtering):
| Kind | Int | Description |
|---|---|---|
| File | 1 | |
| Module | 2 | |
| Namespace | 3 | |
| Package | 4 | |
| Class | 5 | |
| Method | 6 | |
| Property | 7 | |
| Field | 8 | |
| Constructor | 9 | |
| Enum | 10 | |
| Interface | 11 | |
| Function | 12 | |
| Variable | 13 | |
| Constant | 14 |
Example - find only classes:
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "Service",
"substring_matching": true,
"include_kinds": [5] # Class only
})
Efficiency Tips
- Use
relative_pathto scope searches - much faster than searching entire codebase - Start with
include_body: false- get structure first, read code only when needed - Use
depth: 0initially - expand to children only when exploring specific classes - Combine with Brain memory - create Brain memory notes for important architectural findings
Triggers
| Trigger Phrase | Operation |
|---|---|
how do I find a symbol |
find_symbol with name_path_pattern |
how do I explore a file's structure |
get_symbols_overview with depth |
how do I trace references |
find_referencing_symbols |
how do I search code patterns |
search_for_pattern with regex |
what methods does this class have |
find_symbol with depth=1 |
When to Use
Use this skill when:
- Exploring class/function definitions with structural accuracy
- Tracing method call hierarchies across files
- Analyzing imports and dependencies
- Need code intelligence beyond text matching
Use Grep/text search instead when:
- Searching for string literals or comments
- Finding patterns in config files or YAML
- Looking for TODO/FIXME markers
- Simple keyword search across non-code files
Use code-architecture instead when:
- Performing full architectural analysis with memory persistence
- Building knowledge graphs from code structure
Anti-Patterns
| Avoid | Why | Instead |
|---|---|---|
| Searching entire codebase without relative_path | Slow, noisy results | Scope with relative_path parameter |
| Starting with include_body=true | Wastes tokens on code you may not need | Start with include_body=false, read selectively |
| Using depth > 1 on large modules | Returns excessive nested symbols | Use depth=0 or depth=1, expand as needed |
| Using text grep for symbol definitions | Matches comments, strings, false positives | Use find_symbol for structural accuracy |
| Skipping get_symbols_overview | Jumping to find_symbol without context | Start with overview to understand file structure |
Verification
After symbol analysis:
- [ ] Correct symbol found (not a similarly named one)
- [ ] References traced to all call sites
- [ ] Scope was narrowed with relative_path where possible
- [ ] Results were token-efficient (include_body only when needed)
Language Support
Serena works with any language that has an LSP server configured:
- Python (pyright/pylsp)
- TypeScript/JavaScript (tsserver)
- Rust (rust-analyzer)
- Go (gopls)
- Java (jdtls)
- And more...
The specific features available depend on the language server's capabilities.
04 同仓库更多 Skills
validation-authority
Treat upstream validators as authoritative. Align local config to them. Use when validation fails unexpectedly, before modifying validator behavior, or when tempted to change upstream tool code.
using-brain-memory
Guidance for using Brain semantic memory effectively. Applies Zettelkasten atomic note principles with observations and relations. Use when deciding whether to query or create notes, structuring note content, or understanding the semantic knowledge graph.
threat-modeling
Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong.
taste-lints
Custom lints with agent-readable remediation instructions. Enforces taste invariants (file size, naming conventions, structured logging, complexity) and surfaces errors that agents can act on directly. Use when writing or reviewing code to catch style violations early.
style-enforcement
Validate code against style rules from .editorconfig, StyleCop.json, and Directory.Build.props. Detects line ending violations, naming convention issues, indentation problems, and charset mismatches across C#, Python, TypeScript, and JavaScript. Produces JSON reports for pre-commit hooks and CI pipelines.
steering-matcher
Match file paths against steering file glob patterns to determine applicable steering guidance. Use when orchestrator needs to inject context-aware guidance based on files being modified.