From 5d6c9f7ec95d721db72fb2d930f155217ab7a035 Mon Sep 17 00:00:00 2001
From: Yisroel Baum <yisroel.d.baum@gmail.com>
Date: Sat, 2 May 2026 22:15:23 +0300
Subject: [PATCH] add llm anti-patterns to context files

name the LLM-default constructs this project forbids in
explicit before/after tables. catching the trap by pattern
match is more reliable than expecting a general rule to be
applied at write time. backend table covers PHP traps
(arrow fns, inline FQCNs, default params, stored refs, em
dashes, short names); frontend table covers JS/template/
cypress traps.
---
 ai/backend-context.md  | 19 +++++++++++++++++++
 ai/frontend-context.md | 15 +++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/ai/backend-context.md b/ai/backend-context.md
index fca41f0..e59b9a6 100644
--- a/ai/backend-context.md
+++ b/ai/backend-context.md
@@ -43,3 +43,22 @@ ValueObjects) into Entities, DTOs, Repositories, Use Cases, and Fakes
 
 Run `php-cs-fixer fix` on worked-on directories before committing (uses the
 existing `.php-cs-fixer.dist.php` config).
+
+## LLM anti-patterns
+
+Constructs LLMs default to that this project forbids. Name the trap
+explicitly so you catch yourself before writing it.
+
+| Anti-pattern | Forbidden | Required |
+|---|---|---|
+| Arrow function | `fn ($x) => $x->getId()` | `function ($x) { return $x->getId(); }` |
+| Inline FQCN type | `function f(): \Psr\Http\Message\ResponseInterface` | `use Psr\Http\Message\ResponseInterface;` then `function f(): ResponseInterface` |
+| Inline `::class` | `Container::get(\App\Foo\Bar::class)` | `use App\Foo\Bar;` then `Container::get(Bar::class)` |
+| Default param | `function f(int $count = 10)` | `function f(int $count)` |
+| Default in fake | `public function create(Dto $dto, bool $strict = true)` | no default; every caller passes a value |
+| Lookup returns stored ref | `return $this->items[$id] ?? null;` | rebuild a new instance with the stored fields |
+| Short variable name | `$t`, `$n`, `$res`, `$req`, `$e` | `$text`, `$node`, `$response`, `$request`, `$exception` |
+| Em dash | `// fetches user — by email` | `// fetches user - by email` |
+
+When generating code, scan the diff for these patterns before writing it
+to disk. If you catch one mid-write, rewrite that line.
diff --git a/ai/frontend-context.md b/ai/frontend-context.md
index 8757e1f..5e279aa 100644
--- a/ai/frontend-context.md
+++ b/ai/frontend-context.md
@@ -31,3 +31,18 @@ with surrounding files. (TODO: wire up format/lint when added.)
 Frontend changes are often a template plus its page-level JS counterpart -
 commit them together as a single logical unit, per the "one logical change
 per commit" rule in `shared.md`.
+
+## LLM anti-patterns
+
+Constructs LLMs default to that this project forbids on the frontend.
+
+| Anti-pattern | Forbidden | Required |
+|---|---|---|
+| Short variable name | `t`, `n`, `res`, `req`, `e`, `el`, `ev` | `text`, `node`, `response`, `request`, `submitEvent`, `element`, `clickEvent` |
+| Em dash in code/comments | `// loads texts — owner only` | `// loads texts - owner only` |
+| Inline `<script>` in templates | `<script>doStuff()</script>` in a `.php` template | put logic in `public/js/<page>.js`, load via `<script src=...>` |
+| Hardcoded admin URLs in user-facing JS | `fetch('/api/admin/...')` from a non-admin page JS | call user-scoped endpoints from user pages, admin endpoints only from admin pages |
+| Cypress test logging in as the wrong role | `cy.loginAsAdmin()` in a non-admin spec | match the role to the page under test (`loginAsUser` for `/home`, `/texts`; `loginAsAdmin` for `/admin/*`) |
+
+When generating code, scan the diff for these patterns before writing it
+to disk.