A reference your coding agent consults mid-task. Every entry says when to apply it, and when not to. Read it here, fetch it as Markdown, query it over MCP, or install it as a skill.
Measured on the reference’s own examples
- Lines of code
- −17%
- 401 → 331 lines
- Technical debt
- −55%
- 51 → 23 branches
- Code smells
- −100%
- 23 → 0 smells
Measured across the 23 worked examples in the code smells, before and after each fix.
Every pattern, misapplied and applied.
Agents reproduce the textbook shape, misuse included. Here is the shape that goes wrong beside the one the entry recommends, in TypeScript, Python, Go and Java. Pick a language once and every example follows.
Singleton
Misapplied. A hidden global. Every caller depends on it, and tests can't replace it.
Applied. Create one instance at the composition root and pass it in.
class Database {interface Db { private static instance?: Database; query(sql: string, args: unknown[]): Promise<Row[]>; private constructor() {} static get(): Database { return (Database.instance ??= new Database()); }}}class OrderService {class OrderService { constructor(private readonly db: Db) {} total(id: string) { total(id: string) { // Hidden dependency: tests can't swap it. return this.db.query( return Database.get().query( "select total from orders where id = ?", [id]); "select total from orders where id = ?", [id]); } }}}// main.ts: one instance, created once, passed in.const orders = new OrderService(new PgDb(env.DATABASE_URL));class Database { private static instance?: Database; private constructor() {} static get(): Database { return (Database.instance ??= new Database()); }interface Db { query(sql: string, args: unknown[]): Promise<Row[]>;}class OrderService { constructor(private readonly db: Db) {} total(id: string) { // Hidden dependency: tests can't swap it. return Database.get().query( return this.db.query( "select total from orders where id = ?", [id]); }}// main.ts: one instance, created once, passed in.const orders = new OrderService(new PgDb(env.DATABASE_URL));The best pattern is often no pattern.
Agents over-engineer. Every entry here starts from the problem it solves and names the simpler fix: a function, a lookup table, a language feature, or a small refactoring.
- Criticism of PatternsThe main arguments against design patterns, including missing language features, misuse, and over-engineering, and how to apply patterns without those failures.
- Choosing a PatternA decision guide that maps concrete code symptoms to the pattern that fixes them, and tells you when plain code beats any pattern.
- How Agents Should Use This ReferenceRules for AI coding agents using this reference: diagnose a named smell, read the exclusions first, apply one technique at a time and verify with tests.
- How to RefactorRefactor in small named steps, run tests after each one, never mix in behavior changes, and stop when the code is clean enough for the task at hand.
Measured with the server off and on.
A deliberately messy 840-line TypeScript order system was copied into two identical repositories, and the same coding agent with the same prompt refactored both: once with the aipatterns MCP server and its skills, once without. One static analyzer scored both result trees. With the server, the agent removed nearly twice as much code and duplication.
One run per condition on a small fixture; every number is measured from the archived result trees. A comprehensive benchmark across more models and coding agents is coming soon.
Meet the MCP serverNet source lines
Lower is betterDuplicated lines
Lower is betterMaintainability index
Higher is betterBehavior preserved. Every original test passes and the strict typecheck reports zero errors in both arms — 67/67 with the server, 72/72 without. The with-MCP run made 8 tool calls to the aipatterns server — smell detection, treatment and refactoring lookups, pattern-fit checks — and worked through 4 skills.
Questions, answered.
What your agent does with this, why connecting asks you to sign in, what it costs, and what leaves your machine.
I don't know any design patterns. Is this still for me?
Yes. You don't need to learn them yourself. Your agent looks them up while it works, and every entry says when a pattern is the wrong call, so it stops reaching for one just because it can.
Which tools does it work with?
Any agent that speaks MCP: Claude Code, Cursor, VS Code, Codex and others. If yours doesn't, install the skills instead, or have it fetch any page as Markdown by adding .md to the URL.
Why does connecting the MCP server ask me to sign in?
The server is OAuth-protected. On first connect your client opens a browser to sign in with GitHub or email. The account is how tokens are issued and usage is metered - the pages and skills don't need an account.
Does it cost anything?
No. It's free, with no API key to manage. The MCP server enforces a daily allowance per account, currently 100 tool calls per UTC day; the skills and pages have no limits.
Will it make my agent write more code?
Usually less. Most entries name a simpler fix first, such as a function, a lookup table or a small refactoring, and the agent reads “Do not use it when” before applying anything.
Does it read or send my code anywhere?
No. Your agent sends a short description of the problem and gets reference text back. Your code stays on your machine. Your account keeps a sign-in record and a daily call count - the privacy page lists everything that is stored.
My AI-generated codebase is already a mess. Can this help?
Ask your agent to find the code smells in a file or folder. Each smell links to the refactorings that fix it, applied in small steps so things keep working between changes.
Which languages are covered?
Code examples are in TypeScript, Python, Go and Java. The ideas apply to any language your agent writes.
Give your agent a reference it can cite.
Add the MCP server or install the skills. No account, no key, nothing to host.
Also works with
- Cursor
- VS Code
- Codex
- Any MCP client
Claude Code
One command, then ask as you normally would.
claude mcp add --transport http aipatterns https://aipatterns.dev/mcpnpx skills add https://aipatterns.dev