Agent skill

serena-code-architecture

Architectural analysis workflow using Serena symbols and Forgetful memory. Use when analyzing project structure, documenting architecture, creating component entities, or building knowledge graphs from code.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/serena-code-architecture-rjmurillo-ai-agents-2

SKILL.md

Architectural Analysis with Serena + Forgetful

This skill guides systematic architectural analysis using Serena's symbol-level understanding, with optional persistence to Forgetful's knowledge graph.

Triggers

Trigger Phrase Operation
analyze the architecture of this project Full 6-phase analysis workflow
map out the codebase structure Phase 1-3 discovery and component mapping
trace dependencies for this component Phase 4 dependency tracing
create architecture memories Phase 5-6 memory and entity creation
what components does this project have Phase 3 core component mapping

When to Use This Skill

Use this skill when:

  • Analyzing a new codebase before implementing changes
  • Documenting existing architecture for a project
  • Creating component entities and relationships in Forgetful
  • Understanding dependencies and call hierarchies
  • Building a knowledge graph from code structure

Use using-serena-symbols instead when:

  • Quick symbol lookup without memory persistence
  • Finding a specific class or method definition
  • Tracing references for a single symbol

Analysis Workflow

Phase 1: Project Structure Discovery

Understand the high-level layout:

python
# Get directory structure
mcp__plugin_serena_serena__list_dir({
  "relative_path": ".",
  "recursive": false
})

# Identify key directories (src/, app/, lib/, etc.)
mcp__plugin_serena_serena__list_dir({
  "relative_path": "src",
  "recursive": true
})

Goal: Identify entry points, main modules, and organizational patterns.

Phase 2: Entry Point Analysis

Find the application entry points:

python
# Look for main/app files
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "if __name__.*==.*__main__|def main\\(|app\\s*=\\s*FastAPI|createApp",
  "restrict_search_to_code_files": true
})

# Get symbols from entry file
mcp__plugin_serena_serena__get_symbols_overview({
  "relative_path": "src/main.py",
  "depth": 1
})

Phase 3: Core Component Mapping

Identify and analyze major components:

python
# Find all service/controller/model classes
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "Service",
  "substring_matching": true,
  "include_kinds": [5],  # Class only
  "depth": 1
})

# For each major component, get full structure
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "AuthService",
  "include_body": false,
  "depth": 1  # Get methods
})

Phase 4: Dependency Tracing

Understand how components connect:

python
# Find who uses AuthService
mcp__plugin_serena_serena__find_referencing_symbols({
  "name_path": "AuthService",
  "relative_path": "src/services/auth.py"
})

# Find what AuthService depends on
mcp__plugin_serena_serena__find_symbol({
  "name_path_pattern": "AuthService/__init__",
  "include_body": true
})

Phase 5: Create Architectural Memories (Optional)

Store findings in Forgetful:

python
# First, find/create the project
execute_forgetful_tool("list_projects", {"repo_name": "owner/repo"})

# Create memory for architectural insight
execute_forgetful_tool("create_memory", {
  "title": "AuthService: Core authentication component",
  "content": "AuthService handles JWT validation, user sessions, and OAuth flows. Dependencies: UserRepository, TokenService, CacheService. Used by: all API endpoints via middleware.",
  "context": "Discovered during architectural analysis",
  "keywords": ["auth", "jwt", "service", "architecture"],
  "tags": ["architecture", "component"],
  "importance": 8,
  "project_ids": [PROJECT_ID]
})

Phase 6: Entity Graph Creation (Optional)

Create entities for major components:

python
# Check if entity exists first
execute_forgetful_tool("search_entities", {"query": "AuthService"})

# Create component entity
execute_forgetful_tool("create_entity", {
  "name": "AuthService",
  "entity_type": "other",
  "custom_type": "Service",
  "notes": "Core authentication service - JWT, OAuth, sessions",
  "tags": ["service", "auth"],
  "project_ids": [PROJECT_ID]
})

# Create relationships
execute_forgetful_tool("create_entity_relationship", {
  "source_entity_id": AUTH_SERVICE_ID,
  "target_entity_id": USER_REPO_ID,
  "relationship_type": "depends_on",
  "strength": 0.9
})

# Link entity to memories
execute_forgetful_tool("link_entity_to_memory", {
  "entity_id": AUTH_SERVICE_ID,
  "memory_id": ARCH_MEMORY_ID
})

Relationship Types

Standard relationship types for architecture:

Type Use For
uses General usage (A uses B)
depends_on Dependency (A requires B)
calls Direct function/method calls
extends Class inheritance
implements Interface implementation
connects_to External connections (DB, API)
contains Composition (A contains B)

Entity Types for Architecture

Type Use For
Service Business logic services
Repository Data access layer
Controller Request handlers
Middleware Request/response processing
Model Data models/entities
Library External dependencies
Framework Framework components

Example: FastAPI Project Analysis

python
# 1. Find routers
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "APIRouter\\(\\)|router\\s*=",
  "restrict_search_to_code_files": true
})

# 2. Analyze router structure
mcp__plugin_serena_serena__get_symbols_overview({
  "relative_path": "src/routers/users.py",
  "depth": 1
})

# 3. Find dependency injection
mcp__plugin_serena_serena__search_for_pattern({
  "substring_pattern": "Depends\\(",
  "restrict_search_to_code_files": true,
  "context_lines_before": 1,
  "context_lines_after": 1
})

# 4. Trace service dependencies
mcp__plugin_serena_serena__find_referencing_symbols({
  "name_path": "get_current_user",
  "relative_path": "src/dependencies/auth.py"
})

# 5. Create architecture memory
execute_forgetful_tool("create_memory", {
  "title": "FastAPI app structure: Routers + Dependencies",
  "content": "App uses router-based organization with dependency injection. Routers: /users, /auth, /products. Dependencies: get_current_user, get_db. All routes require auth except /auth/login.",
  "context": "FastAPI architecture analysis",
  "keywords": ["fastapi", "router", "dependency-injection"],
  "tags": ["architecture", "pattern"],
  "importance": 8,
  "project_ids": [PROJECT_ID]
})

Analysis Checklist

  • Directory structure mapped
  • Entry points identified
  • Major components catalogued
  • Dependencies traced
  • External connections documented
  • Key patterns identified
  • Memories created for insights
  • Entities created for components (if applicable)
  • Relationships mapped (if applicable)

Anti-Patterns

Avoid Why Instead
Analyzing every class as a component Creates noise in entity graph Focus on major architectural components only
Reading full source before overview Wastes tokens on unneeded code Start with get_symbols_overview, read selectively
Creating entities without memories Entities lack context without linked knowledge Create memory first, then entity, then link them
Skipping dependency tracing Misses critical coupling relationships Always run Phase 4 for components you create entities for
Documenting WHAT without WHY Memories become stale quickly Focus memories on rationale and trade-offs

Verification

After architectural analysis:

  • Directory structure mapped (Phase 1)
  • Entry points identified (Phase 2)
  • Major components catalogued (Phase 3)
  • Dependencies traced for key components (Phase 4)
  • Memories created with importance 7+ for insights
  • Entities linked to corresponding memories

Tips

  1. Work incrementally - Don't try to analyze everything at once
  2. Focus on interfaces - Public methods/APIs matter more than internals
  3. Document decisions - Create memories for WHY, not just WHAT
  4. Use entities sparingly - Only major components, not every class
  5. Link across projects - Architecture patterns often apply elsewhere

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results