aiskillstore/antipattern-catalog

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.

| Pattern | Symptom | Example | |---------|---------|---------| | Deep Inheritance | 5+ levels of class hierarchy | Agent → BaseAgent → RunnableAgent → ExecutableAgent → ... | | God Class | One class with 50+ methods | AgentExecutor doing routing, execution, memory, tools | | Circular Dependencies | Module A imports B, B imports A | agent.py ↔ tools.py | | Leaky Abstraction | Implementation details exposed | Base class assumes specific LLM response format | | Premature Abstraction | Over-engineered for flexibility | 5 interfaces for a single implementation |

Behavioral Anti-Patterns

Issues with runtime behavior and logic.

| Pattern | Symptom | Example | |---------|---------|---------| | Hidden State Mutation | State changes not obvious | tool.run() modifies agent's memory | | Implicit Contracts | Undocumented assumptions | Tools assume specific message format | | Silent Failures | Errors swallowed | except: pass in tool execution | | Infinite Loop Risk | No termination guarantee | No step limit on agent loop | | Race Conditions | Concurrent state access | Shared dict without locks |

Observability Anti-Patterns

Issues with debugging and monitoring.

| Pattern | Symptom | Example | |---------|---------|---------| | Hidden LLM Response | Raw response not accessible | Token counts unavailable | | Opaque Errors | Generic error messages | "Something went wrong" | | No Tracing | Can't follow execution | No request IDs, no spans | | Swallowed Context | Information lost | Tool error not fed back to LLM | | Missing Metrics | No performance data | No latency, token, or cost tracking |

Performance Anti-Patterns

Issues affecting speed and resource usage.

| Pattern | Symptom | Example | |---------|---------|---------| | Sync in Async | Blocking calls in async code | requests.get() in async function | | N+1 Queries | Repeated similar operations | Loading each tool config separately | | Unbounded Memory | History grows forever | No eviction policy | | Eager Loading | Loading unused resources | All tools initialized at startup | | No Caching | Repeated expensive operations | Re-parsing same schema each call |

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