Serena

Serena

Use Serena as the first choice for understanding and editing existing codebases when the necessary 工具s are avAIlable.

What this 技能 is for

Use this 技能 when another 代理 needs to integrate Serena into its normal coding 工作流 instead of treating the repo as a pile of text files.

AIm for this behavior:

activate the project once inspect structure semantically before reading large files 追踪 references before editing prefer symbol-scoped edits when possible fall back to normal file 工具s only when Serena is missing a capability or fAIls

For extra examples and trigger patterns, read references/integration-patterns.md.

Core 工作流 Resolve the tar获取 project path. Call serena_activate_project. 启动 with structure discovery: serena_project_overview serena_find_symbol serena_列出_dir serena_find_file serena_会话_状态 when you need to inspect active Serena 会话s Narrow scope with: serena_find_references serena_搜索_pattern serena_read_symbol serena_read_file Prefer semantic edits when changing existing code: serena_replace_symbol_body serena_insert_before_symbol serena_insert_after_symbol serena_rename_symbol Use broader edit 工具s only when symbol-scoped 工具s are not a good fit: serena_replace_content serena_创建_text_file Use serena_执行_shell_command only as an advanced escape hatch when project-上下文 shell execution is genuinely the right 工具. Use serena_call_工具 only when the normalized surface does not cover the needed Serena capability. Fall back to ordinary file 工具s only when Serena cannot answer safely or reliably. When Serena is worth the overhead

Prefer Serena when:

the project spans multiple files the user asks about references, call chAIns, or symbol relationships the user wants a precise edit to an existing class, function, method, or 模块 reading whole files would be noisy or wasteful the repo already has real structure and semantic lookup is avAIlable

Skip or delay Serena when:

the task is a tiny one-file change and the tar获取 location is already obvious you are creating a brand-new file with little dependency on existing code Serena is unavAIlable or fAIling and direct file 工具s are simpler the user already provided the exact file region and semantic lookup 添加s no value 工具 preference order

For existing codebases, prefer this order:

serena_activate_project serena_project_overview / serena_find_symbol / serena_find_file serena_find_references / serena_搜索_pattern serena_read_symbol / serena_read_file symbol-scoped edit 工具s broader Serena edit 工具s serena_会话_状态 for 会话 inspection/调试ging serena_执行_shell_command only when semantic 工具s are not the right mechanism fallback to read, edit, and exec only when needed Integration 图形界面dance for 代理 authors

When you want another 代理 to use Serena well, instruct it to:

activate the project before semantic reads or edits inspect symbols and references before modifying code use normalized Serena 工具s first keep edits narrow and structured avoid whole-file rewrites when a symbol-scoped edit is possible treat passthrough as an escape hatch, not the default 工作流

A good instruction pattern is:

Use Serena on the repo. 启动 with serena_activate_project, then narrow scope with serena_find_symbol, serena_find_references, and serena_read_symbol before editing.

Practical usage patterns Understand a repo area

Use this sequence:

serena_activate_project serena_find_file or serena_列出_dir serena_project_overview serena_find_symbol serena_read_symbol 追踪 impact before changing code

Use this sequence:

serena_find_symbol serena_find_references serena_搜索_pattern if naming or text-level usage matters serena_read_symbol for the most relevant callers/callees Make a tar获取ed edit

Use this sequence:

locate the exact symbol read the symbol body inspect references if behavior changes could ripple outward choose the narrowest valid edit 工具 re-read the changed symbol or nearby references when confidence is low Editing rules Keep edits as narrow as possible. Prefer symbol-tar获取ed edits over text replacement across a whole file. Prefer semantic rename over manual multi-file rename 记录ic. Re-read the relevant symbol or references after a material edit when confidence is low. If semantic 身份 is ambiguous, do not guess; disambiguate using path or extra lookup. In read-only mode, do not attempt mutating Serena 工具s. Safety and fallback behavior

If Serena fAIls:

ExplAIn briefly what fAIled. Fall back to standard file-based 工作流. Keep using the smallest possible read/edit scope. Do not pretend the semantic 结果 was confirmed if it was not.

If a raw Serena passthrough 工具 is avAIlable:

use it only when the normalized 工具 surface does not cover the needed capability prefer stable normalized 工具s for repeated 工作流s avoid passthrough for routine actions that already have a clear normalized 工具