Skip to content

About

Design pattern discipline for AI-generated code. When AI writes the code, the architect must still be you.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

ai-architect-patterns

When AI writes the code, the architect must still be you.

A discipline for getting maintainable output from AI coding agents (Cursor, Claude, Codex, Copilot, etc.). The problem they all share: give them a shallow prompt and you get working code with five philosophies mashed together — spaghetti architecture. The fix: declare the design patterns in the brief, then verify them in the diff.

Synthesized from @ersinkoc's thread, 22 Aug 2026.

The thesis

"It works, let's move on" wins short-term and destroys projects long-term. Software is a living organism — it needs solid architecture to survive.

AI agents are great at generating code and terrible at consistency across runs. The same prompt two days apart can land in two different architectures. The only sustainable solution is human-in-the-loop architecture: the architect names the patterns, the agent fills in the body, the architect reviews the seam.

The 5 patterns (must be named in the brief)

Each pattern ships with an AI anti-pattern it kills and a one-line verification step:

Pattern Category AI anti-pattern it kills Verify in diff
Factory Method Creational if-else hell over concrete classes per provider No new XxxService in caller code — all instances come from factory
Singleton Creational Repeated new Logger() per module, scattered config reads Single point-of-instantiation; metaclass / double-checked lock visible
Adapter Structural Direct import openai, raw third-party types in domain code All third-party imports cross an adapters/ module
Strategy Behavioral Monolithic switch(provider) / match blocks per request Each branch = its own Strategy class
Observer Behavioral Cross-module direct calls + manual fan-out Subject exposes subscribe/unsubscribe; emit goes through bus/event

Common additions the brief may also declare: Repository, Builder, Decorator, Facade, Chain of Responsibility. Same rule — name them or don't use them.

Workflow

  1. Read the brief. If no pattern is declared → ask, don't guess. Pattern-free briefs produce pattern-free code.

  2. Force a brief skeleton:

    TASK: <verb> <module>
    PATTERNS REQUIRED:
      - Creational: <which one + why>
      - Structural: <which one + why or "none">
      - Behavioral: <which one + why or "none">
    CONSTRAINTS:
      - <what must NOT appear>
      - <interface surface — what callers see>
    INTERFACE: <signature or shape>
    TESTS: <behavior through interface only>
    
  3. Generate. Then audit the diff against the table above — find the AI anti-pattern shape, confirm the pattern shape exists. If mismatch → regenerate, do not deliver.

  4. Hand back. Deliver the diff plus a one-line per pattern: Factory ✓ at adapters/payment_factory.py:14.

What this is NOT

  • Not "always apply every pattern." Patterns chosen wrong = ceremony with no payoff. Decide per-module.
  • Not framework-prescriptive. Patterns are language-agnostic — Python, TS, Rust, Go all implement the same shapes.
  • Not a substitute for design judgment. The skill enforces discipline; it doesn't replace thinking.

Pitfalls

  • Pattern ceremony without payoff — Singleton on a config that already has one global is tight coupling, no gain.
  • "Strategy" as label for if-else — A real Strategy is its own class file.
  • Adapter that wraps everything — If the adapter adds zero behavior, delete it and import the lib directly.
  • Observer fan-out explosion — >100 subscribers means you have an event bus, not an Observer; rename or split.
  • Factory returns the wrong thing — factory.create(name) returning Any defeats the seam.
  • Singleton for things that aren't single — Multi-tenant config, multiple DB pools: use scoped factory, not Singleton.

Files

  • SKILL.md — full reference (works as a Hermes skill too)

License

MIT — see LICENSE.

About

Design pattern discipline for AI-generated code. When AI writes the code, the architect must still be you.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors