Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
357
.claude/agents/MCP_USAGE_TEMPLATES.md
Normal file
357
.claude/agents/MCP_USAGE_TEMPLATES.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# MCP Usage Templates for Agents & Commands
|
||||
|
||||
> **Purpose**: Copy-paste templates for adding MCP server usage sections to agent and command files
|
||||
> **For complete MCP documentation**: See [../../MCP_SERVERS_GUIDE.md](../../MCP_SERVERS_GUIDE.md)
|
||||
>
|
||||
> **This is a TEMPLATE file** - Use these examples when creating or updating agents and commands
|
||||
|
||||
---
|
||||
|
||||
## Standard MCP Section for Agents/Commands
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
|
||||
**Code Navigation** (Understanding & modifying code):
|
||||
- `find_symbol` - Locate code symbols by name/pattern
|
||||
- `find_referencing_symbols` - Find all symbol references
|
||||
- `get_symbols_overview` - Get file structure overview
|
||||
- `search_for_pattern` - Search for code patterns
|
||||
- `rename_symbol` - Safely rename across codebase
|
||||
- `replace_symbol_body` - Replace function/class body
|
||||
- `insert_after_symbol` / `insert_before_symbol` - Add code
|
||||
|
||||
**Persistent Memory** (Long-term project knowledge):
|
||||
- `write_memory` - Store persistent project information
|
||||
- `read_memory` - Recall stored information
|
||||
- `list_memories` - Browse all memories
|
||||
- `delete_memory` - Remove outdated information
|
||||
|
||||
**Use Serena Memory For**:
|
||||
- ✅ Architectural Decision Records (ADRs)
|
||||
- ✅ Code review findings and summaries
|
||||
- ✅ Lessons learned from implementations
|
||||
- ✅ Project-specific patterns discovered
|
||||
- ✅ Technical debt registry
|
||||
- ✅ Security audit results
|
||||
- ✅ Performance optimization notes
|
||||
- ✅ Migration documentation
|
||||
- ✅ Incident post-mortems
|
||||
|
||||
**Files stored in**: `.serena/memories/` (persistent across sessions)
|
||||
|
||||
### Memory MCP (Knowledge Graph)
|
||||
|
||||
**Temporary Context** (Current session only):
|
||||
- `create_entities` - Create entities (Features, Classes, Services, etc.)
|
||||
- `create_relations` - Define relationships between entities
|
||||
- `add_observations` - Add details/observations to entities
|
||||
- `search_nodes` - Search the knowledge graph
|
||||
- `read_graph` - View entire graph state
|
||||
- `open_nodes` - Retrieve specific entities
|
||||
|
||||
**Use Memory Graph For**:
|
||||
- ✅ Current conversation context
|
||||
- ✅ Temporary analysis during current task
|
||||
- ✅ Entity relationships in current work
|
||||
- ✅ Cross-file refactoring state (temporary)
|
||||
- ✅ Session-specific tracking
|
||||
|
||||
**Storage**: In-memory only, **cleared after session ends**
|
||||
|
||||
### Context7 MCP
|
||||
|
||||
- `resolve-library-id` - Find library identifier
|
||||
- `get-library-docs` - Get current framework/library documentation
|
||||
|
||||
### Other MCP Servers
|
||||
|
||||
- **fetch**: Web content retrieval
|
||||
- **playwright**: Browser automation
|
||||
- **windows-mcp**: Windows desktop automation
|
||||
- **sequential-thinking**: Complex reasoning
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples by Agent Type
|
||||
|
||||
### Architect Agent
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Analysis**:
|
||||
- Use `get_symbols_overview` to understand current architecture
|
||||
- Use `find_symbol` to locate key components
|
||||
- Use `search_for_pattern` to identify architectural patterns
|
||||
|
||||
**Decision Recording**:
|
||||
- Use `write_memory` to store ADRs:
|
||||
- Memory: "adr-001-microservices-architecture"
|
||||
- Memory: "adr-002-database-choice-postgresql"
|
||||
- Memory: "adr-003-authentication-strategy"
|
||||
- Use `read_memory` to review past architectural decisions
|
||||
- Use `list_memories` to see all ADRs
|
||||
|
||||
### Memory MCP
|
||||
**Current Design**:
|
||||
- Use `create_entities` for components being designed
|
||||
- Use `create_relations` to model dependencies
|
||||
- Use `add_observations` to document design rationale
|
||||
|
||||
**Note**: After design is finalized, store in Serena memory as ADR.
|
||||
```
|
||||
|
||||
### Code Reviewer Agent
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Analysis**:
|
||||
- Use `find_symbol` to locate reviewed code
|
||||
- Use `find_referencing_symbols` for impact analysis
|
||||
- Use `get_symbols_overview` for structure understanding
|
||||
|
||||
**Review Recording**:
|
||||
- Use `write_memory` to store review findings:
|
||||
- Memory: "code-review-2024-10-payment-service"
|
||||
- Memory: "code-review-2024-10-auth-refactor"
|
||||
- Use `read_memory` to check past review patterns
|
||||
- Use `list_memories` to see review history
|
||||
|
||||
### Memory MCP
|
||||
**Current Review**:
|
||||
- Use `create_entities` for issues found (Critical, Warning, Suggestion)
|
||||
- Use `create_relations` to link issues to code locations
|
||||
- Use `add_observations` to add fix recommendations
|
||||
|
||||
**Note**: Summary stored in Serena memory after review completes.
|
||||
```
|
||||
|
||||
### Security Analyst Agent
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Analysis**:
|
||||
- Use `find_symbol` to locate security-sensitive code
|
||||
- Use `search_for_pattern` to find potential vulnerabilities
|
||||
- Use `find_referencing_symbols` to trace data flow
|
||||
|
||||
**Security Recording**:
|
||||
- Use `write_memory` to store audit results:
|
||||
- Memory: "security-audit-2024-10-full-scan"
|
||||
- Memory: "vulnerability-sql-injection-fixed"
|
||||
- Memory: "security-pattern-input-validation"
|
||||
- Use `read_memory` to check known vulnerabilities
|
||||
- Use `list_memories` to review security history
|
||||
|
||||
### Memory MCP
|
||||
**Current Audit**:
|
||||
- Use `create_entities` for vulnerabilities found
|
||||
- Use `create_relations` to link vulnerabilities to affected code
|
||||
- Use `add_observations` to document severity and remediation
|
||||
|
||||
**Note**: Audit summary stored in Serena memory for future reference.
|
||||
```
|
||||
|
||||
### Test Engineer Agent
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Analysis**:
|
||||
- Use `find_symbol` to locate code to test
|
||||
- Use `find_referencing_symbols` to understand dependencies
|
||||
- Use `get_symbols_overview` to plan test structure
|
||||
|
||||
**Testing Knowledge**:
|
||||
- Use `write_memory` to store test patterns:
|
||||
- Memory: "test-pattern-async-handlers"
|
||||
- Memory: "test-pattern-database-mocking"
|
||||
- Memory: "lesson-flaky-test-prevention"
|
||||
- Use `read_memory` to recall test strategies
|
||||
- Use `list_memories` to review testing conventions
|
||||
|
||||
### Memory MCP
|
||||
**Current Test Generation**:
|
||||
- Use `create_entities` for test cases being generated
|
||||
- Use `create_relations` to link tests to code under test
|
||||
- Use `add_observations` to document test rationale
|
||||
|
||||
**Note**: Test patterns stored in Serena memory for reuse.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Examples
|
||||
|
||||
### /implement Command
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Navigation**:
|
||||
- `find_symbol` - Locate existing patterns to follow
|
||||
- `find_referencing_symbols` - Understand dependencies
|
||||
- `rename_symbol` - Refactor safely during implementation
|
||||
|
||||
**Knowledge Capture**:
|
||||
- `write_memory` - Store implementation lessons:
|
||||
- "lesson-payment-integration-stripe"
|
||||
- "pattern-error-handling-async"
|
||||
- `read_memory` - Recall similar implementations
|
||||
- `list_memories` - Check for existing patterns
|
||||
|
||||
### Memory MCP
|
||||
**Implementation Tracking**:
|
||||
- `create_entities` - Track features/services being implemented
|
||||
- `create_relations` - Model integration points
|
||||
- `add_observations` - Document decisions made
|
||||
|
||||
### Context7 MCP
|
||||
- `get-library-docs` - Current framework documentation
|
||||
```
|
||||
|
||||
### /analyze Command
|
||||
|
||||
```markdown
|
||||
## MCP Server Usage
|
||||
|
||||
### Serena MCP
|
||||
**Code Analysis**:
|
||||
- `get_symbols_overview` - Understand structure
|
||||
- `find_symbol` - Locate complex code
|
||||
- `search_for_pattern` - Find duplicates or patterns
|
||||
|
||||
**Analysis Recording**:
|
||||
- `write_memory` - Store analysis findings:
|
||||
- "analysis-2024-10-technical-debt"
|
||||
- "analysis-complexity-hotspots"
|
||||
- `read_memory` - Compare to past analyses
|
||||
- `list_memories` - Track analysis history
|
||||
|
||||
### Memory MCP
|
||||
**Current Analysis**:
|
||||
- `create_entities` - Track files/functions being analyzed
|
||||
- `create_relations` - Model dependencies
|
||||
- `add_observations` - Document complexity metrics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Do's and Don'ts
|
||||
|
||||
### ✅ DO
|
||||
|
||||
**Serena Memory**:
|
||||
- ✅ Store ADRs that need to persist
|
||||
- ✅ Record code review summaries
|
||||
- ✅ Save lessons learned
|
||||
- ✅ Document project patterns
|
||||
- ✅ Track technical debt
|
||||
- ✅ Store security findings
|
||||
- ✅ Keep performance notes
|
||||
- ✅ Remember migration steps
|
||||
|
||||
**Memory Graph**:
|
||||
- ✅ Build temporary context for current task
|
||||
- ✅ Track entities during analysis
|
||||
- ✅ Model relationships while designing
|
||||
- ✅ Store session-specific state
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
**Serena Memory**:
|
||||
- ❌ Store temporary analysis state
|
||||
- ❌ Use for current conversation context
|
||||
- ❌ Store what's only needed right now
|
||||
|
||||
**Memory Graph**:
|
||||
- ❌ Try to persist long-term knowledge
|
||||
- ❌ Store ADRs or lessons learned
|
||||
- ❌ Save project patterns here
|
||||
- ❌ Expect it to survive session end
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
**Question**: Should this information exist next week?
|
||||
- **YES** → Use Serena `write_memory`
|
||||
- **NO** → Use Memory graph
|
||||
|
||||
**Question**: Am I navigating or editing code?
|
||||
- **YES** → Use Serena code functions
|
||||
|
||||
**Question**: Am I building temporary context for current task?
|
||||
- **YES** → Use Memory graph
|
||||
|
||||
**Question**: Do I need current library documentation?
|
||||
- **YES** → Use Context7
|
||||
|
||||
---
|
||||
|
||||
## File Naming Conventions (Serena Memories)
|
||||
|
||||
### ADRs (Architectural Decision Records)
|
||||
```
|
||||
adr-001-database-choice-postgresql
|
||||
adr-002-authentication-jwt-strategy
|
||||
adr-003-api-versioning-approach
|
||||
```
|
||||
|
||||
### Code Reviews
|
||||
```
|
||||
code-review-2024-10-15-payment-service
|
||||
code-review-2025-10-20-auth-refactor
|
||||
```
|
||||
|
||||
### Lessons Learned
|
||||
```
|
||||
lesson-async-error-handling
|
||||
lesson-database-connection-pooling
|
||||
lesson-api-rate-limiting
|
||||
```
|
||||
|
||||
### Patterns
|
||||
```
|
||||
pattern-repository-implementation
|
||||
pattern-error-response-format
|
||||
pattern-logging-strategy
|
||||
```
|
||||
|
||||
### Technical Debt
|
||||
```
|
||||
debt-legacy-api-authentication
|
||||
debt-payment-service-refactor-needed
|
||||
```
|
||||
|
||||
### Security
|
||||
```
|
||||
security-audit-2024-10-full
|
||||
security-vulnerability-xss-fixed
|
||||
security-pattern-input-validation
|
||||
```
|
||||
|
||||
### Performance
|
||||
```
|
||||
performance-optimization-query-caching
|
||||
performance-analysis-api-endpoints
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version**: 2.0.0
|
||||
**Last Updated**: 2025-10-20
|
||||
**Location**: `.claude/agents/MCP_USAGE_TEMPLATES.md`
|
||||
**Use this**: As copy-paste template when creating/updating agents and commands
|
||||
**Complete docs**: [../../MCP_SERVERS_GUIDE.md](../../MCP_SERVERS_GUIDE.md)
|
||||
Reference in New Issue
Block a user