Anti-Pattern Catalog

Documents technical debt and patterns to avoid.

Process

1. Collect observations — Gather issues from Phase 1 & 2 analyses
2. Categorize — Structural, behavioral, observability, performance
3. Assess severity — Critical, major, minor, cosmetic
4. Generate remediation — Suggest fixes for each pattern
5. Create checklist — "Do Not Repeat" guidelines

Anti-Pattern Categories

Structural Anti-Patterns

Issues with code organization, inheritance, and modularity.

Behavioral Anti-Patterns

Issues with runtime behavior and logic.

Observability Anti-Patterns

Issues with debugging and monitoring.

Performance Anti-Patterns

Issues affecting speed and resource usage.

Severity Assessment

Critical (P0)

• Security vulnerabilities
• Data loss risk
• Infinite loops without guards
• Production outage risk

Major (P1)

• Performance issues >2x slowdown
• Poor error handling
• Difficult to extend
• Concurrency bugs

Minor (P2)

• Code style issues
• Minor inefficiencies
• Documentation gaps
• Inconsistent patterns

Cosmetic (P3)

• Naming conventions
• Formatting
• Minor redundancy

Catalog Entry Template

### [Pattern Name]

**Category**: [Structural/Behavioral/Observability/Performance]
**Severity**: [Critical/Major/Minor/Cosmetic]
**Framework(s)**: [Where observed]

#### Description
[Brief explanation of the anti-pattern]

#### Example
[Code snippet showing the problem]

#### Impact
- [Impact 1]
- [Impact 2]

#### Remediation
[How to fix or avoid this pattern]

#### Code Example (Fixed)
[Corrected code snippet]

Common Anti-Patterns Deep Dive

Deep Inheritance Hell

Problem:

class Agent(BaseAgent):
    pass

class BaseAgent(RunnableAgent):
    pass

class RunnableAgent(ExecutableAgent):
    pass

class ExecutableAgent(ConfigurableAgent):
    pass

class ConfigurableAgent(LoggableAgent):
    pass

class LoggableAgent(ABC):
    pass

# 6 layers! Which method comes from where?

Remediation: Prefer composition over inheritance

class Agent:
    def __init__(
        self,
        executor: Executor,
        config: Config,
        logger: Logger
    ):
        self.executor = executor
        self.config = config
        self.logger = logger

Silent Tool Failures

Problem:

def run_tool(self, tool, args):
    try:
        return tool.execute(args)
    except Exception:
        return None  # Error lost forever!

Remediation: Capture and propagate errors

def run_tool(self, tool, args) -> ToolResult:
    try:
        output = tool.execute(args)
        return ToolResult(success=True, output=output)
    except Exception as e:
        return ToolResult(
            success=False,
            error=f"{type(e).__name__}: {e}",
            traceback=traceback.format_exc()
        )

Hidden LLM Response

Problem:

class LLMWrapper:
    def generate(self, prompt: str) -> str:
        response = self.client.chat(prompt)
        return response.content  # Token counts, model info lost!

Remediation: Expose full response

class LLMWrapper:
    def generate(self, prompt: str) -> LLMResponse:
        response = self.client.chat(prompt)
        return LLMResponse(
            content=response.content,
            model=response.model,
            usage=TokenUsage(
                prompt=response.usage.prompt_tokens,
                completion=response.usage.completion_tokens
            ),
            raw=response  # Always keep raw
        )

Output Template

# Anti-Pattern Catalog: [Analysis Name]

## Summary

| Severity | Count |
|----------|-------|
| Critical | 2 |
| Major | 5 |
| Minor | 8 |
| Cosmetic | 3 |

## Critical Issues

### 1. [Pattern Name]
[Full catalog entry]

### 2. [Pattern Name]
[Full catalog entry]

## Major Issues

### 1. [Pattern Name]
[Full catalog entry]

...

## Do Not Repeat Checklist

- [ ] Never use more than 3 levels of inheritance
- [ ] Always expose raw LLM response with token counts
- [ ] Never swallow exceptions without logging
- [ ] Always include step limits on agent loops
- [ ] Never mutate shared state without locks
- [ ] Always provide structured error feedback to LLM
...

Integration

• Inputs from: All Phase 1 & 2 analysis skills
• Feeds into: architecture-synthesis for design decisions
• Related: comparative-matrix for pattern comparison