serena-code-workflow

name	serena-code-workflow
description	Семантический воркфлоу для кода через Serena MCP - приоритет перед raw reads и grep. Используй для: изучи код, проиндексируй проект, найди символы, найди ссылки на символ, рефакторинг, проследи реализацию, инспектируй файл. EN triggers: navigate code, find symbol, find references, semantic refactor, trace usages, inspect file, code lookup, symbol search, where is X defined.

Serena Code Workflow

Purpose

Use Serena MCP as the primary semantic layer for code work. The goal is low semantic entropy: understand structure before reading bodies, edit symbols instead of brittle line ranges, keep project knowledge synchronized, and prefer scalable patterns over quick text surgery.

User-facing conversation stays in Russian unless the user asks otherwise. Repository documentation, code comments, commit messages, memory files, plan files, and research archive files are written in English.

When To Use

Use this skill without waiting for explicit invocation when the task asks to:

• Inspect, index, explore, understand, map, review, edit, refactor, or trace repository code.
• Analyze projects, directories, files, symbols, classes, functions, references, call sites, dependencies, or implementation scope.
• Find where a feature is implemented, how code is connected, what can be deleted, or what will be affected by a change.
• Make non-trivial code changes where semantic structure matters more than raw text matching.
• Use or prefer Serena MCP, LSP-aware tools, symbol navigation, or project memories.

If Serena is unavailable or the file type is not supported, state the fallback and continue with OpenCode built-in tools (read, grep, glob, edit). Do not block progress just because a preferred MCP tool is missing.

Tool Priority (read)

For reading code, follow this order unless the task is trivial or the current session lacks a listed tool:

1. activate_project when the active project is unclear.
2. check_onboarding_performed to verify whether Serena project onboarding exists.
3. list_memories to discover durable project knowledge.
4. read_memory only for relevant memories inferred from names.
5. get_symbols_overview to map top-level file structure without reading full files.
6. find_symbol with include_body=false to discover children, overloads, and symbol paths.
7. find_symbol with include_body=true only for the exact implementation needed.
8. find_referencing_symbols to trace callers, usages, dead code risk, and refactor impact.
9. search_for_pattern only for broad text sweeps, non-symbol text, or fallback coverage.

Tool Priority (edit)

For editing code, prefer:

1. find_symbol(include_body=true) to read the current implementation.
2. replace_symbol_body for whole-symbol replacement.
3. insert_before_symbol or insert_after_symbol for structured additions.
4. rename_symbol for LSP-aware symbol renames.
5. safe_delete_symbol if available and suitable.

Use raw grep (via grep tool), direct file reads, and edit tool only when Serena cannot answer the question, when the task is text-level rather than symbol-level, or when the needed edit is a tiny known-location change.

Indexing And Project Discovery

For Serena project setup and indexing, follow Serena's project workflow. The official indexing operation is the Serena project command serena project index; MCP tools then use the resulting project and language-server state for semantic navigation. Do not invent a nonexistent MCP "index directory" tool.

When a project is not onboarded, use Serena onboarding patterns and memory tools as the source of durable project context.

Quality Rules

Code is the source of truth. Memories, plans, and docs must be checked against actual code, git diff, and task-specific verification.

Do not read entire files when get_symbols_overview plus targeted find_symbol is enough. Do not use grep as the first move for symbol-level questions.

For non-trivial decisions, make a short explicit plan before editing. If the task requires external technical research, use the tech-research or web-research skill first and then return to Serena for local code impact.

After meaningful project changes, use the serena-memory-sync skill before final stop so .serena/memories stays accurate.

Output

For investigation-only work, report:

• Scope: what code was inspected.
• Evidence: Serena tools or fallback sources used.
• Findings: concrete facts with file paths or symbol names.
• Next steps: implementation or verification actions.

For implementation work, keep the final concise: what changed, how it was verified, and any residual risk.

Anti-patterns

• Reading whole files for symbol-level questions
• Using grep before get_symbols_overview for symbol search
• Editing line ranges when replace_symbol_body would do
• Skipping memories before exploring
• Assuming Serena is unavailable without checking