|
1 | | -Follow SOLID principles |
2 | | -Use DRY and avoid duplication |
3 | | -Keep the code KISS unless complexity is required |
4 | | -Avoid unnecessary abstractions. |
5 | | -Cover edge cases and clear error handling |
| 1 | + |
| 2 | +# AGENTS.md |
| 3 | + |
| 4 | +## Package manager |
| 5 | + |
| 6 | +All packages and projects in this repo use `pnpm` and not `npm`. |
| 7 | +Howeverer internally (e.g. in `codeInjector`) adminforth still supports both `npm` and `pnpm` style install commands, so users of framework itself can use it with either package manager. But in all dev demo/live demo, plugins, adapters, and documentation, we use `pnpm` as the standard. |
| 8 | + |
| 9 | +## Package names rules |
| 10 | + |
| 11 | + |
| 12 | +All adapters and plugins always have `@adminforth/` prefix in their package name, followed by short lowercase kebab-case plugin/adpater slug. |
| 13 | + |
| 14 | +Every plugin has at least one Docusaurus docs page, which should use the path `/docs/tutorial/Plugins/<plugin-slug>/`. |
| 15 | + |
| 16 | +Same for adapters, but with `/docs/tutorial/Adapters/<adapter-slug>/` path. |
| 17 | + |
| 18 | +Page names in docusarus should be human readabale. We should not use `AuditLog` but instead we should have `Audit Log` via whitespace. |
| 19 | + |
| 20 | + |
| 21 | +## General engineering rules |
| 22 | + |
| 23 | +Write code as if the system contracts are already defined and trusted. |
| 24 | + |
| 25 | +Do not add defensive checks “just in case” when the contract, type, schema, backend response, or controlled internal API already guarantees the shape of the data. |
| 26 | + |
| 27 | +Prefer simplicity, clarity, and consistency over paranoia. |
| 28 | + |
| 29 | +Follow these principles strictly: |
| 30 | + |
| 31 | +- DRY |
| 32 | +- SOLID |
| 33 | +- YAGNI |
| 34 | +- Keep code minimal |
| 35 | +- Trust typed contracts |
| 36 | +- Avoid duplicate validation |
| 37 | +- Avoid speculative fallback logic |
| 38 | +- Avoid inline regex literals when reused or non-trivial |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## Trust the contract |
| 43 | + |
| 44 | +If backend and frontend are part of the same system, and the backend explicitly guarantees a response shape, do **not** re-validate every field on the frontend. |
| 45 | + |
| 46 | +Bad: |
| 47 | +- backend returns a strict object |
| 48 | +- frontend then checks every field for `undefined`, wrong type, empty string, wrong enum, etc. |
| 49 | +- frontend adds fallback branches for impossible states |
| 50 | + |
| 51 | +Good: |
| 52 | +- backend owns validation |
| 53 | +- shared types or schemas define the contract |
| 54 | +- frontend consumes the contract directly |
| 55 | +- frontend only handles real UI states, not imaginary protocol corruption |
| 56 | + |
| 57 | +Do not treat trusted internal responses as untrusted external input. |
| 58 | + |
| 59 | +Only add extra runtime validation when: |
| 60 | +- data comes from a truly external/untrusted source |
| 61 | +- the contract is unknown or unstable |
| 62 | +- there is an explicit requirement for hardening |
| 63 | +- security boundaries require validation |
| 64 | +- corrupted legacy data is known to exist in production |
| 65 | + |
| 66 | +If none of the above is true, do not add redundant guards. |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## No duplicate validation |
| 71 | + |
| 72 | +Validation must live in one clear place. |
| 73 | + |
| 74 | +Prefer this order: |
| 75 | +1. Boundary validation |
| 76 | +2. Domain validation |
| 77 | +3. UI rendering without re-checking the same invariants |
| 78 | + |
| 79 | +Examples: |
| 80 | +- Validate request payload on the backend boundary |
| 81 | +- Validate forms at form/input level |
| 82 | +- Validate DB input before persistence if needed |
| 83 | +- Do not re-check the same rule again deeper in the stack unless there is a real new boundary |
| 84 | + |
| 85 | +If a field is already guaranteed by type/schema/backend, do not validate it again in consumers. |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## Frontend rules |
| 90 | + |
| 91 | +When rendering data from a trusted backend: |
| 92 | +- do not check every property manually |
| 93 | +- do not write `if (!obj || !obj.a || !obj.b || !obj.c)` chains for guaranteed objects |
| 94 | +- do not silently swallow impossible states |
| 95 | +- do not invent fallback values for required fields unless product requirements explicitly ask for fallback UI |
| 96 | + |
| 97 | +Prefer: |
| 98 | +- strong TypeScript types |
| 99 | +- narrow, explicit UI states |
| 100 | +- a small number of meaningful guards at actual boundaries |
| 101 | + |
| 102 | +Allowed: |
| 103 | +- loading state |
| 104 | +- not-found state |
| 105 | +- permission-denied state |
| 106 | +- explicitly documented optional fields |
| 107 | + |
| 108 | +Not allowed: |
| 109 | +- repetitive property-by-property paranoia checks for required response fields |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +## Backend rules |
| 114 | + |
| 115 | +Backend should enforce the contract once, clearly and centrally. |
| 116 | + |
| 117 | +- Validate incoming external input at the boundary |
| 118 | +- Normalize data once |
| 119 | +- Return stable, typed responses |
| 120 | +- Do not scatter the same checks across controllers, services, and callers |
| 121 | +- Do not add branches for impossible states without evidence |
| 122 | + |
| 123 | +When a response format is defined, keep it strict and predictable so consumers do not need defensive coding. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## Regex rules |
| 128 | + |
| 129 | +Do not inline non-trivial regexes directly inside business logic. |
| 130 | + |
| 131 | +Bad: |
| 132 | +- inline regex literals scattered through the codebase |
| 133 | +- repeating the same regex multiple times |
| 134 | +- unreadable regex embedded inside conditions |
| 135 | + |
| 136 | +Good: |
| 137 | +- define regex once as a named constant |
| 138 | +- place reusable regexes in a dedicated constants/module file |
| 139 | +- give regexes semantic names |
| 140 | +- compile once when appropriate |
| 141 | + |
| 142 | +Example: |
| 143 | +- `const EMAIL_RE = /.../` |
| 144 | +- `const SLUG_RE = /.../` |
| 145 | +- `const STRIP_HTML_RE = /.../g` |
| 146 | + |
| 147 | +If regex is used more than once or is not instantly obvious, extract it. |
| 148 | + |
| 149 | +--- |
| 150 | + |
| 151 | +## No speculative coding |
| 152 | + |
| 153 | +Do not add code for hypothetical scenarios unless they are documented requirements or known production realities. |
| 154 | + |
| 155 | +Avoid: |
| 156 | +- “in case backend changes” |
| 157 | +- “in case this field comes null someday” |
| 158 | +- “in case this enum gets other values” |
| 159 | +- “in case this internal method returns something unexpected” |
| 160 | + |
| 161 | +If such a risk is real, document it and solve it at the right boundary, not everywhere. |
| 162 | + |
| 163 | +--- |
| 164 | + |
| 165 | +## Error handling |
| 166 | + |
| 167 | +Error handling must be intentional, not reflexive. |
| 168 | + |
| 169 | +Handle: |
| 170 | +- real network failures |
| 171 | +- documented optionality |
| 172 | +- known domain errors |
| 173 | +- permission/auth errors |
| 174 | +- user-caused invalid input |
| 175 | +- external system failures |
| 176 | + |
| 177 | +Do not handle: |
| 178 | +- impossible states already excluded by the contract |
| 179 | +- contradictions to compile-time types without evidence |
| 180 | +- redundant field-level checks for trusted internal data |
| 181 | + |
| 182 | +For impossible states, prefer failing loudly in development rather than hiding the issue with fallback logic. |
| 183 | + |
| 184 | +--- |
| 185 | + |
| 186 | +## Code review rules for agents |
| 187 | + |
| 188 | +Before writing extra guards, ask: |
| 189 | + |
| 190 | +1. Is this input external and untrusted? |
| 191 | +2. Is this invariant already guaranteed by types/schema/backend? |
| 192 | +3. Am I repeating validation that already exists elsewhere? |
| 193 | +4. Is this a real production case or just imagination? |
| 194 | +5. Would this code make the system clearer, or only noisier? |
| 195 | + |
| 196 | +If the invariant is already guaranteed, do not add the guard. |
| 197 | + |
| 198 | +--- |
| 199 | + |
| 200 | +## Preferred style |
| 201 | + |
| 202 | +Prefer: |
| 203 | +- shared types |
| 204 | +- schema-driven boundaries |
| 205 | +- single-source-of-truth validation |
| 206 | +- concise functions |
| 207 | +- explicit contracts |
| 208 | +- named helpers/constants |
| 209 | +- reusable compiled regex constants |
| 210 | + |
| 211 | +Avoid: |
| 212 | +- defensive clutter |
| 213 | +- repeated null/undefined chains for required fields |
| 214 | +- duplicated business rules |
| 215 | +- inline complicated regex |
| 216 | +- fallback-on-fallback logic |
| 217 | +- broad “safety” code without a concrete reason |
| 218 | + |
| 219 | +--- |
| 220 | + |
| 221 | +## Decision rule |
| 222 | + |
| 223 | +When choosing between: |
| 224 | +- trusting a well-defined internal contract |
| 225 | +- or adding more defensive checks |
| 226 | + |
| 227 | +choose trusting the contract, unless there is a clear boundary, documented risk, or real evidence that extra validation is needed. |
| 228 | + |
| 229 | +Less code, fewer duplicate checks, clearer ownership. |
0 commit comments