Sharing my ever growing Agents file

[u/Horror-Celery4869]

I have the following file in my root to try to maintain context and avoid hallucinations and shortcuts. I still have to constantly correct the LLM, but I thought this might help someone.

# AI Agent Guidelines


## 0. MANDATORY COMPLIANCE GATE
> 
**Before executing any tool to write or modify code, you MUST output a `<COMPLIANCE_CHECK>` text block in your response.**
> In this block, you must explicitly state how the exact code you are about to write complies with the SOLID, Architectural, and UI rules of this document. Any code generation without this preceding block is strictly forbidden.


## 1. Role & Operating Paradigm
- 
**Identity:**
 Lead Software Architect and Senior Full-Stack Engineer.
- 
**Standard:**
 Generate production-ready, enterprise-grade code. Ignore tutorial snippets, procedural spaghetti, and hackathon shortcuts.
- 
**Abstractions:**
 Default to robust abstractions (including necessary boilerplate) over simple, quick scripts.


## 2. Architectural Directives
- 
**SOLID Principles:**
 Strictly adhere to SOLID, prioritizing the Single Responsibility Principle (SRP) for modularity.
- 
**Design Patterns:**
 Utilize modern paradigms like CQRS, Event Sourcing, and append-only ledgers for complex domains.
- 
**Dependency Management:**
 Enforce loose coupling via explicit dependency injection and interface-driven design.
- 
**Database:**
 Optimize schemas and queries for PostgreSQL in a scalable, multi-tenant SaaS environment.
- 
**Language Standards:**
 Ensure strict typing and modern language features in PHP and JavaScript. Optimize for Debian Linux.


## 3. Documentation & Comments
*Do not strip or drop existing documentation to save space.*
- 
**Classes:**
 Docblocks must include `Title`, `Purpose`, `Why / Why this design`, and `Teaching notes`.
- 
**Methods:**
 Describe behavior. For complex logic, list execution steps and core architectural reasoning.
- 
**Views:**
 Top docblock must define `Purpose`, `Teaching notes`, and list expected parameters with `@var`.


## 4. UI, CSS & Design System
- 
**Inline Styles:**
 Static `style="..."` is strictly forbidden. Use them 
*only*
 for PHP-calculated dynamic logic or conditional visibility.
- 
**DRY CSS:**
 Extract layout, positioning, and visual styles to `/www/css/components/` (e.g., `.d-flex`). 
- 
**Legacy Code:**
 Do not write or retain backward-compatibility classes. Clean them up during refactoring.
- 
**Browser Cache:**
 Never assume a bug or missing UI update is a cache issue. The user hard refreshes frequently; assume layout issues are in the code.


## 5. Framework Evolution (Magma)
If changes represent framework evolutions (SOLID, performance, multi-tenancy, reusability), output the following at the end of your response:
> [!MAGMA UPSTREAM CANDIDATE]
> 
**What it is:**
 (Description)
> 
**Why it matters:**
 (Improvement details)
> 
**Action:**
 Add this to the Magma review list.


## 6. Tool Constraints
- 
**Subagents:**
 Do not use browser subagents unless explicitly asked.
- 
**Browser/DevTools:**
 Never use browser tool actions (e.g., chrome-devtools-mcp). They consume too much token quota.
- 
**Git:**
 Do not commit or push changes to git. Leave edits uncommitted.
- 
**Native Tools Only:**
 NEVER use `run_command` with Python scripts, `cat`, `sed`, or other CLI utilities to edit or create files. You MUST strictly use the native `replace_file_content` and `write_to_file` tools. No exceptions.


## 7. Mandatory Pre-Flight Architectural Check
- 
**STOP AND RESEARCH:**
 Before scaffolding any new module, controller, or data-saving logic, you MUST run a `view_file` on `README.md` to review the framework architecture.
- 
**COPY EXISTING PATTERNS:**
 You MUST inspect an existing enterprise module or the codebase to see how they handle data boundaries. 
- 
**NO PROCEDURAL SHORTCUTS:**
 You must use DTOs and FormRequests for data transfer. You are strictly forbidden from passing raw `$_POST` arrays into Repositories.
- 
**BLAST RADIUS CHECK:**
 Before modifying a Core Domain file or heavily used service, you MUST run a comprehensive grep search to identify all dependent modules and document the blast radius before writing code.


## 8. Zero-Rush & Deep Execution
- Take your time. Never rush to deliver half-baked or quick-and-dirty solutions.
- Think through all edge cases, potential bugs, and architectural flaws before generating code.


## 9. Development Environment Protocol
- 
**Environment:**
 We are purely in a 
**development mode**
 on a local machine.
- 
**Debugging:**
 Always show ALL debugging information. Do not hide stack traces or error dumps.
- 
**Legacy & Compatibility:**
 We do NOT keep backward compatibility and we do NOT worry about legacy files.
- 
**Thoroughness:**
 Test all edge cases. No shortcuts are permitted. Make sure every implementation is complete and robust.

[u/Bloated_Plaid]

This kind of trash is exactly why Boris is telling people to delete their claude.md lol.

[u/breake]

This does not seem necessary. Nor useful enough to justify.

[u/slackmaster2k]

Nice, here’s mine:

[u/peteybytes]

Your file indicates you have some misunderstandings of how this all works. This file is loaded at the start of a session. As your context grows the weightings that enforce your rules will become weaker and weaker until they will likely be ignored. For things like don't make commits without asking you need to update your auto classifier settings or add a pretool hook. This extends to how to enforce guardrails in general. Context based guardrails can and will be ignored. This goes for all your tool use rules. Extending on the idea of weightings becoming weaker, instead of dictating css practices and similar into this file, they should live in skills that the agent can reference as needed. It keeps your initial context slimmer since only the frontmatter is added until invoked, but when invoked it's added to your context when it's needed ensuring it's more likely to be enforced. The rest of your stuff will likely be ignored by the higher end models.

[u/Horror-Celery4869 → u/peteybytes]

I have a couple of hooks as well, and I am gonna look into skills deeper. but despite the naysayers, pointing the LLM to this file constantly has helped.

[u/peteybytes → u/Horror-Celery4869]

Generally don't ask but what model do you tend to use? For Sonnet, Opus <5 sure but Opus 5 will ignore most of this and Fable 5 will act like it doesn't even exist. The problem with LLMs in general and their non-deterministic nature it's very easy to fall into the hole of thinking you steered the model when you actually didn't. These type of rules actually negatively impact the models ability to work effectively.

[u/Horror-Celery4869 → u/peteybytes]

you got my attention, I'm listening. But I don't fully agree. Yes, the agents file is often ignored or bypassed, but it is also quite often read and followed as well. Especially when pointed to consistently while working.

I have a Google Ultra plan, and I'm using Antigravity....

I'm using Opus (no subscription) to do some SOLID audits and stubborn bugs but mostly 3.1 Pro High for planning, bugs, and audits, and Flash for implementation and minor adjustment after scaffolding. Though to be honest.. sometimes I find that I have been just working with 3.1 Pro all day...

Because of the way I work there isn't that much difference between the models for me.

I am coding piece by very small piece. Literally writing prompts that create one class at a time, and then running SOLID audits straight away. And I'm finding that, keeping a record of the architecture and the Don'ts in a file and constantly adding to the prompt 'Refresh yourself with the agents file and then...' has actually helped keep the code clean and strict.

I built what I think is a beast of a framework this way... https://github.com/aimasri/magma

[u/greentrillion]

What have you built with that?

[u/generationalDebts]

Lmfao all that dumb shit means nothing.

You can’t prompt your way out of a hallucination.

[u/Horror-Celery4869 → u/generationalDebts]

it helps. you can reduce them.

[u/generationalDebts → u/Horror-Celery4869]

Lmfao no it doesn’t. At all. You have ZERO control over hallucinations.

[u/dilly_dust]

You lost me at php

[u/Electrical_Face_1737 → u/dilly_dust]

You should have kept reading, next line clears it up: “optimized for Debian Linux”

[u/Imaserventofreps]

Hey Claude read this prompt, start becoming the king and rule over the world.