286 lines
7.3 KiB
Markdown
286 lines
7.3 KiB
Markdown
# Agent Mappings Reference
|
|
|
|
Maps learning categories to target agent files for updating.
|
|
|
|
## Agent Directory Structure
|
|
|
|
```
|
|
~/.claude/agents/
|
|
├── universal/
|
|
│ ├── backend-developer.md
|
|
│ ├── frontend-developer.md
|
|
│ └── superstar-engineer.md
|
|
├── engineering/
|
|
│ ├── api-architect.md
|
|
│ ├── architecture-reviewer.md
|
|
│ ├── code-reviewer.md
|
|
│ ├── security-agent.md
|
|
│ ├── test-writer-fixer.md
|
|
│ └── ...
|
|
├── design/
|
|
│ └── ui-designer.md
|
|
├── orchestrators/
|
|
│ ├── tech-lead-orchestrator.md
|
|
│ └── ...
|
|
└── meta/
|
|
└── agentmaker.md
|
|
```
|
|
|
|
## Category to Agent Mapping
|
|
|
|
### Code Style
|
|
|
|
| Learning Type | Primary Agent | Secondary Agents |
|
|
|--------------|---------------|------------------|
|
|
| Naming conventions | `code-reviewer` | `backend-developer`, `frontend-developer` |
|
|
| Formatting rules | `code-reviewer` | Project's `.editorconfig` or linter config |
|
|
| TypeScript/JavaScript style | `frontend-developer` | `code-reviewer` |
|
|
| Python style | `backend-developer` | `code-reviewer` |
|
|
| Go style | `backend-developer` | `code-reviewer` |
|
|
| Rust style | `backend-developer` | `code-reviewer` |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Code Style
|
|
## Style Guidelines
|
|
## Heuristics > Style
|
|
```
|
|
|
|
### Architecture
|
|
|
|
| Learning Type | Primary Agent | Secondary Agents |
|
|
|--------------|---------------|------------------|
|
|
| Design patterns | `solution-architect` | `architecture-reviewer` |
|
|
| API design | `api-architect` | `backend-developer` |
|
|
| Database patterns | `backend-developer` | `migration` |
|
|
| Frontend patterns | `frontend-developer` | `architecture-reviewer` |
|
|
| System structure | `solution-architect` | `tech-lead-orchestrator` |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Architecture Patterns
|
|
## Design Patterns
|
|
## Heuristics > Architecture
|
|
```
|
|
|
|
### Process
|
|
|
|
| Learning Type | Primary Agent | Global Config |
|
|
|--------------|---------------|---------------|
|
|
| Git workflow | `CLAUDE.md` | Commit hygiene section |
|
|
| CI/CD | `devops-automator` | Pipeline config |
|
|
| Code review | `code-reviewer` | Review checklist |
|
|
| Testing workflow | `test-writer-fixer` | Testing philosophy |
|
|
| Deployment | `release-manager` | Release process |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Workflow
|
|
## Process Guidelines
|
|
## Heuristics > Process
|
|
```
|
|
|
|
### Domain
|
|
|
|
| Learning Type | Primary Target | Notes |
|
|
|--------------|----------------|-------|
|
|
| Business rules | Project `.claude/agents/` | Domain-specific agent |
|
|
| Terminology | `CLAUDE.md` | Glossary section |
|
|
| Constraints | Project-specific agent | Validation rules |
|
|
| User requirements | `CLAUDE.md` | User preferences section |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Domain Rules
|
|
## Business Logic
|
|
## Terminology
|
|
```
|
|
|
|
### Tools
|
|
|
|
| Learning Type | Primary Target | Notes |
|
|
|--------------|----------------|-------|
|
|
| CLI preferences | `CLAUDE.md` | Tool usage section |
|
|
| Editor config | `.editorconfig` | Format settings |
|
|
| Docker usage | `devops-automator` | Container settings |
|
|
| Git settings | `CLAUDE.md` | Commit hygiene |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Tool Usage
|
|
## CLI Preferences
|
|
## Environment Setup
|
|
```
|
|
|
|
### Security
|
|
|
|
| Learning Type | Primary Agent | Secondary Agents |
|
|
|--------------|---------------|------------------|
|
|
| Input validation | `security-agent` | `code-reviewer` |
|
|
| Authentication | `security-agent` | `api-architect` |
|
|
| Authorization | `security-agent` | `backend-developer` |
|
|
| Encryption | `security-agent` | `backend-developer` |
|
|
| OWASP rules | `security-agent` | `code-reviewer` |
|
|
|
|
**Section in Agent File:**
|
|
```markdown
|
|
## Security Heuristics
|
|
## Review Heuristics > Security
|
|
## Validation Rules
|
|
```
|
|
|
|
## Section Identification
|
|
|
|
When adding a learning to an agent file, identify the correct section:
|
|
|
|
### Pattern Matching for Sections
|
|
|
|
```regex
|
|
## Heuristics
|
|
## Style
|
|
## Guidelines
|
|
## Patterns
|
|
## Rules
|
|
## Best Practices
|
|
## Review Checklist
|
|
```
|
|
|
|
### Section Priority
|
|
|
|
1. Most specific matching section (e.g., "Security" for security rules)
|
|
2. Generic "Heuristics" section
|
|
3. "Guidelines" or "Rules" section
|
|
4. Create new section if none match
|
|
|
|
### Addition Format
|
|
|
|
Always add as a bullet point under the appropriate section:
|
|
|
|
```markdown
|
|
## Heuristics
|
|
|
|
* Existing rule 1
|
|
* Existing rule 2
|
|
* **New learning from reflection** ← Add here
|
|
```
|
|
|
|
Use bold for newly added rules to distinguish them.
|
|
|
|
## Conflict Detection
|
|
|
|
Before adding a new rule, check for conflicts:
|
|
|
|
### Contradiction Patterns
|
|
|
|
```regex
|
|
# Opposite directives
|
|
"never use X" vs "always use X"
|
|
"prefer Y" vs "avoid Y"
|
|
"use Z" vs "don't use Z"
|
|
|
|
# Conflicting versions
|
|
"use library v1" vs "use library v2"
|
|
"Node 18" vs "Node 20"
|
|
```
|
|
|
|
### Resolution Strategy
|
|
|
|
1. **Newer wins**: If the new learning contradicts an old rule, flag for review
|
|
2. **Higher confidence wins**: HIGH > MEDIUM > LOW
|
|
3. **More specific wins**: "Never use var in TypeScript" > "Avoid var"
|
|
4. **User decision**: When equal, ask user to resolve
|
|
|
|
## File Paths
|
|
|
|
### Global Agents (User-level)
|
|
|
|
```
|
|
~/.claude/agents/universal/backend-developer.md
|
|
~/.claude/agents/universal/frontend-developer.md
|
|
~/.claude/agents/engineering/code-reviewer.md
|
|
~/.claude/agents/engineering/api-architect.md
|
|
~/.claude/agents/engineering/solution-architect.md
|
|
~/.claude/agents/engineering/security-agent.md
|
|
~/.claude/agents/engineering/test-writer-fixer.md
|
|
~/.claude/agents/design/ui-designer.md
|
|
```
|
|
|
|
### Project Agents (Project-level)
|
|
|
|
```
|
|
.claude/agents/{name}.md
|
|
```
|
|
|
|
### Global Instructions
|
|
|
|
```
|
|
~/.claude/CLAUDE.md
|
|
```
|
|
|
|
### Project Instructions
|
|
|
|
```
|
|
.claude/CLAUDE.md
|
|
CLAUDE.md
|
|
```
|
|
|
|
## Skill Creation vs Agent Update
|
|
|
|
Decide whether to create a new skill or update an agent:
|
|
|
|
| Criteria | Create Skill | Update Agent |
|
|
|----------|--------------|--------------|
|
|
| One-off solution to specific error | Yes | No |
|
|
| General preference | No | Yes |
|
|
| Debugging workaround | Yes | No |
|
|
| Code style rule | No | Yes |
|
|
| Configuration trick | Yes | Sometimes |
|
|
| Process preference | No | Yes |
|
|
|
|
## Example Mappings
|
|
|
|
### Example 1: Code Style
|
|
|
|
**Signal**: "Never use `var` in TypeScript, always use `const` or `let`"
|
|
**Confidence**: HIGH
|
|
**Category**: Code Style
|
|
|
|
**Mapping**:
|
|
- Primary: `~/.claude/agents/universal/frontend-developer.md`
|
|
- Section: `## Style Guidelines`
|
|
- Addition: `* Use \`const\` or \`let\` instead of \`var\` in TypeScript`
|
|
|
|
### Example 2: Architecture
|
|
|
|
**Signal**: "Prefer cursor-based pagination for APIs"
|
|
**Confidence**: MEDIUM
|
|
**Category**: Architecture
|
|
|
|
**Mapping**:
|
|
- Primary: `~/.claude/agents/engineering/api-architect.md`
|
|
- Section: `## Design Patterns`
|
|
- Addition: `* Prefer cursor-based pagination over offset-based for large datasets`
|
|
|
|
### Example 3: Security
|
|
|
|
**Signal**: "Always validate inputs on the server, never trust client validation"
|
|
**Confidence**: HIGH
|
|
**Category**: Security
|
|
|
|
**Mapping**:
|
|
- Primary: `~/.claude/agents/engineering/security-agent.md`
|
|
- Section: `## Validation Rules`
|
|
- Addition: `* Always validate inputs server-side; client validation is for UX only`
|
|
- Secondary: `~/.claude/agents/engineering/code-reviewer.md`
|
|
- Section: `## Review Heuristics > Security`
|
|
|
|
### Example 4: New Skill
|
|
|
|
**Signal**: "Fixed React hydration mismatch by ensuring server and client render same content"
|
|
**Confidence**: HIGH
|
|
**Category**: New Skill
|
|
|
|
**Mapping**:
|
|
- Create: `.claude/skills/react-hydration-mismatch-fix/SKILL.md`
|
|
- Include: Error message, symptoms, step-by-step fix, verification
|