@activatus/code-standards 3.2.1 → 3.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/Guides/migrating.md +9 -4
- package/docs/Guides/regression-checks.md +1 -0
- package/docs/Guides/setup.md +22 -16
- package/docs/Standards/eslint.md +34 -3
- package/docs/Standards/readable-code.md +30 -1
- package/docs/Standards/working-with-agents.md +5 -1
- package/docs/Structure/folder-structure.md +102 -44
- package/docs/version-history.md +132 -29
- package/package.json +1 -1
- package/scripts/verifyStandards/checkAgentFiles.mjs +50 -8
- package/scripts/verifyStandards/checkConstants.mjs +10 -72
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +5 -1
- package/scripts/verifyStandards/formatReport.mjs +3 -1
- package/scripts/verifyStandards/runChecks.mjs +4 -8
- package/static/templates/AGENTS.md +8 -5
- package/static/templates/docs/development/coding-standards.md +1 -1
- package/static/templates/eslint/nextjs/eslint.config.mjs +11 -0
- package/static/templates/eslint/react/eslint.config.mjs +10 -0
- package/static/templates/eslint/typescript/eslint.config.mjs +10 -0
- package/static/templates/skills/typescript.md +3 -1
- package/static/templates/tests/visual/pageLayout.visual.ts +9 -1
package/docs/Guides/migrating.md
CHANGED
|
@@ -52,6 +52,8 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
|
|
|
52
52
|
|
|
53
53
|
Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **live production site**, before anything changes. Every later stage must pass it unchanged.
|
|
54
54
|
|
|
55
|
+
**Take the baseline first, then move one kind of thing at a time.** The constants moves (Stage 4) and the folder moves (Stage 5a) are separate steps, each followed by a full regression run. When a run fails, only one kind of move can have caused it.
|
|
56
|
+
|
|
55
57
|
## Stage 1 — Formatting
|
|
56
58
|
|
|
57
59
|
Applies setup standards 7, 9 and 10. Three commits, in this order:
|
|
@@ -181,9 +183,12 @@ Applies setup standard 12.1. Move every link into `r`, every piece of text into
|
|
|
181
183
|
|
|
182
184
|
- **Move the values, nothing else.** The page must look and work exactly as before.
|
|
183
185
|
- **No component-level `constants.ts` survives this stage.**
|
|
184
|
-
- **Move
|
|
185
|
-
- **
|
|
186
|
-
- **
|
|
186
|
+
- **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`. Any other file in `lib/constants/` is folded into the standard file that fits.
|
|
187
|
+
- **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
|
|
188
|
+
- **An id moves into the object that uses it.** **CSS written as a string moves to `globals.css`**, never into a constants file. A media query the code reads stays in its object in `animation.ts`.
|
|
189
|
+
- **Only text people see or hear goes in `s`.** Internal strings, such as ids, keys and log messages, stay where they are used: a key in the object that uses them, or a named constant at the top of the file.
|
|
190
|
+
- **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its key: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete any separate lookup object that maps a key to its link.
|
|
191
|
+
- **Every constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
|
|
187
192
|
|
|
188
193
|
## Stage 5 — Components
|
|
189
194
|
|
|
@@ -207,7 +212,7 @@ Applies setup standard 21.
|
|
|
207
212
|
|
|
208
213
|
1. Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. It describes the final layout, so it goes last.
|
|
209
214
|
2. Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
|
|
210
|
-
3. Set `**Code standards version:**`
|
|
215
|
+
3. Set `**Code standards version:**` to the installed package's full version, such as `3.2.2`.
|
|
211
216
|
4. Run the [standards check](/docs/Guides/setup#checking-a-project), and fix what it finds.
|
|
212
217
|
|
|
213
218
|
## Tips
|
|
@@ -66,6 +66,7 @@ It builds the project and starts the production build on port 3100, then measure
|
|
|
66
66
|
- **It runs against a production build**, on its own port, never against `pnpm dev`.
|
|
67
67
|
- **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
|
|
68
68
|
- **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
|
|
69
|
+
- **A code standards update that changes only types may still be applied to a frozen test**, such as replacing `as const` with a real type, with the person's yes. A copy of the template takes the new template whole; a project's own test takes just the typing change. Nothing the test does may change, and the check must still pass against the **existing** baseline, never a new one: passing proves nothing changed.
|
|
69
70
|
|
|
70
71
|
## The blind spot
|
|
71
72
|
|
package/docs/Guides/setup.md
CHANGED
|
@@ -51,7 +51,7 @@ The standards are now in `node_modules/@activatus/code-standards/`:
|
|
|
51
51
|
| `docs/version-history.md` | What changed in each version, and what a project has to do about it |
|
|
52
52
|
| `static/templates/` | The config files to copy: `AGENTS.md`, ESLint, Prettier, Stylelint and the rest |
|
|
53
53
|
|
|
54
|
-
**Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version: `2.
|
|
54
|
+
**Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version, and a project records it in full: `3.2.2`.
|
|
55
55
|
|
|
56
56
|
## 2. Work out where the project is
|
|
57
57
|
|
|
@@ -121,7 +121,7 @@ The list has nothing about branches or commit messages. Those are the project's
|
|
|
121
121
|
|
|
122
122
|
## 4. Working with the agent
|
|
123
123
|
|
|
124
|
-
Do this step every time, straight after step 3. Once the standards are agreed, offer the
|
|
124
|
+
Do this step every time, straight after step 3. Once the standards are agreed, offer the five [Working with Agents](/docs/Standards/working-with-agents) options. All five are optional: offer every one, every time, so the person can fill them in quickly and keep going.
|
|
125
125
|
|
|
126
126
|
First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
|
|
127
127
|
|
|
@@ -148,7 +148,14 @@ Would you like AI to ask you before every commit and push
|
|
|
148
148
|
to git? Yes or no?
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
-
|
|
151
|
+
Then **told about decisions**. **Print this to the person exactly as it is written**:
|
|
152
|
+
|
|
153
|
+
```text
|
|
154
|
+
Would you like AI to tell you about each coding decision
|
|
155
|
+
it makes that the code standards do not cover? Yes or no?
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. If they said yes to being told about decisions, write under **Decisions**: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." If they said no, delete the Decisions line. Write all five answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
|
|
152
159
|
|
|
153
160
|
## 5. Apply the standards
|
|
154
161
|
|
|
@@ -174,12 +181,12 @@ The other standards are rules for how code is written. There is nothing to insta
|
|
|
174
181
|
|
|
175
182
|
**Finish by:**
|
|
176
183
|
|
|
177
|
-
1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's
|
|
184
|
+
1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's full version, such as `3.2.2`. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
|
|
178
185
|
2. Running `pnpm lint`, `pnpm format:check`, the tests and the [standards check](#checking-a-project), and fixing what they find.
|
|
179
186
|
3. **Printing this to the person**, filled in, so every project's handover reads the same:
|
|
180
187
|
|
|
181
188
|
```text
|
|
182
|
-
Code standards set up: version [
|
|
189
|
+
Code standards set up: version [full package version].
|
|
183
190
|
|
|
184
191
|
Set up: [the standards applied, by number]
|
|
185
192
|
Skipped: [numbers and reasons, or "None"]
|
|
@@ -195,12 +202,11 @@ anything that is wrong.
|
|
|
195
202
|
|
|
196
203
|
## Already on this version
|
|
197
204
|
|
|
198
|
-
The project's `AGENTS.md` has the same
|
|
205
|
+
The project's `AGENTS.md` has the same full version as the installed package, such as 3.2.2. There are no version changes to make.
|
|
199
206
|
|
|
200
|
-
1. **
|
|
201
|
-
2. **
|
|
202
|
-
3. **
|
|
203
|
-
4. **Tell the person** what you changed, or that the project was already up to date.
|
|
207
|
+
1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing and being told about decisions. Ask the person any that are not recorded, and record them as step 4 says.
|
|
208
|
+
2. **Run the [standards check](#checking-a-project)**, and fix what it finds.
|
|
209
|
+
3. **Tell the person** what you changed, or that the project was already up to date.
|
|
204
210
|
|
|
205
211
|
---
|
|
206
212
|
|
|
@@ -208,23 +214,23 @@ The project's `AGENTS.md` has the same major version as the installed package, s
|
|
|
208
214
|
|
|
209
215
|
The project already follows the standards, and a newer version is out.
|
|
210
216
|
|
|
211
|
-
**
|
|
217
|
+
**Every new number can ask for work**, whichever part changed. What each part means is in [How versions are numbered](/docs/version-history#how-versions-are-numbered).
|
|
212
218
|
|
|
213
|
-
1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code
|
|
219
|
+
1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code last applied. If it is only a major number, such as `3`, find the full version first: see [Updating a project to a new version](/docs/version-history#updating-a-project-to-a-new-version).
|
|
214
220
|
2. **Update the package:**
|
|
215
221
|
|
|
216
222
|
```bash
|
|
217
223
|
pnpm add -D @activatus/code-standards@latest
|
|
218
224
|
```
|
|
219
225
|
|
|
220
|
-
Its
|
|
226
|
+
Its version is now the newest. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
|
|
221
227
|
|
|
222
|
-
3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the
|
|
228
|
+
3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the entries newer than the project's version. Do not re-read the rest of the standards.
|
|
223
229
|
4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
|
|
224
230
|
5. **Do every other change** as its "What to do" says, and run its "How to check" search.
|
|
225
231
|
6. **Ask any [step 4](#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
|
|
226
232
|
7. **Run the [standards check](#checking-a-project)**, and fix what it finds.
|
|
227
|
-
8. **Set `**Code standards version:**`** in `AGENTS.md` to the
|
|
233
|
+
8. **Set `**Code standards version:**`** in `AGENTS.md` to the installed package's full version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
|
|
228
234
|
|
|
229
235
|
See the [Version History](/docs/version-history) for the full update rules.
|
|
230
236
|
|
|
@@ -254,7 +260,7 @@ It reports, and never changes a file. Each finding gives the standard's number a
|
|
|
254
260
|
| 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
|
|
255
261
|
| 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, no component has its own `constants.ts`, and no other file sits beside the seven standard ones |
|
|
256
262
|
| 13 | Every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
|
|
257
|
-
| 21 | `docs/development/coding-standards.md` records the
|
|
263
|
+
| 21 | `docs/development/coding-standards.md` records the five agent answers under "Details" |
|
|
258
264
|
| 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
|
|
259
265
|
| 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
|
|
260
266
|
| 4 | Every file that exports a function or component has a test file beside it |
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -272,6 +272,14 @@ const NO_SATISFIES = {
|
|
|
272
272
|
"Type a value where it is declared, not with satisfies afterwards.",
|
|
273
273
|
};
|
|
274
274
|
|
|
275
|
+
// Give a value a real type instead. consistent-type-assertions always
|
|
276
|
+
// lets `as const` through, so it is banned here.
|
|
277
|
+
const NO_AS_CONST = {
|
|
278
|
+
selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
|
|
279
|
+
message:
|
|
280
|
+
"Give the value a real type where it is declared, not as const.",
|
|
281
|
+
};
|
|
282
|
+
|
|
275
283
|
const config = [
|
|
276
284
|
{
|
|
277
285
|
ignores: [
|
|
@@ -319,6 +327,7 @@ const config = [
|
|
|
319
327
|
"no-restricted-syntax": [
|
|
320
328
|
"error",
|
|
321
329
|
NO_SATISFIES,
|
|
330
|
+
NO_AS_CONST,
|
|
322
331
|
...RESTRICTED_SYNTAX,
|
|
323
332
|
...SINGLE_OBJECT_PARAMETER,
|
|
324
333
|
],
|
|
@@ -410,6 +419,7 @@ const config = [
|
|
|
410
419
|
rules: {
|
|
411
420
|
"no-restricted-syntax": [
|
|
412
421
|
"error",
|
|
422
|
+
NO_AS_CONST,
|
|
413
423
|
...RESTRICTED_SYNTAX,
|
|
414
424
|
...SINGLE_OBJECT_PARAMETER,
|
|
415
425
|
],
|
|
@@ -489,6 +499,14 @@ const NO_SATISFIES = {
|
|
|
489
499
|
"Type a value where it is declared, not with satisfies afterwards.",
|
|
490
500
|
};
|
|
491
501
|
|
|
502
|
+
// Give a value a real type instead. consistent-type-assertions always
|
|
503
|
+
// lets `as const` through, so it is banned here.
|
|
504
|
+
const NO_AS_CONST = {
|
|
505
|
+
selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
|
|
506
|
+
message:
|
|
507
|
+
"Give the value a real type where it is declared, not as const.",
|
|
508
|
+
};
|
|
509
|
+
|
|
492
510
|
const config = [
|
|
493
511
|
{
|
|
494
512
|
ignores: [
|
|
@@ -545,6 +563,7 @@ const config = [
|
|
|
545
563
|
"no-restricted-syntax": [
|
|
546
564
|
"error",
|
|
547
565
|
NO_SATISFIES,
|
|
566
|
+
NO_AS_CONST,
|
|
548
567
|
...RESTRICTED_SYNTAX,
|
|
549
568
|
...SINGLE_OBJECT_PARAMETER,
|
|
550
569
|
],
|
|
@@ -645,6 +664,7 @@ const config = [
|
|
|
645
664
|
rules: {
|
|
646
665
|
"no-restricted-syntax": [
|
|
647
666
|
"error",
|
|
667
|
+
NO_AS_CONST,
|
|
648
668
|
...RESTRICTED_SYNTAX,
|
|
649
669
|
...SINGLE_OBJECT_PARAMETER,
|
|
650
670
|
],
|
|
@@ -727,6 +747,14 @@ const NO_SATISFIES = {
|
|
|
727
747
|
"Type a value where it is declared, not with satisfies afterwards.",
|
|
728
748
|
};
|
|
729
749
|
|
|
750
|
+
// Give a value a real type instead. consistent-type-assertions always
|
|
751
|
+
// lets `as const` through, so it is banned here.
|
|
752
|
+
const NO_AS_CONST = {
|
|
753
|
+
selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
|
|
754
|
+
message:
|
|
755
|
+
"Give the value a real type where it is declared, not as const.",
|
|
756
|
+
};
|
|
757
|
+
|
|
730
758
|
const config = [
|
|
731
759
|
{
|
|
732
760
|
ignores: [
|
|
@@ -782,6 +810,7 @@ const config = [
|
|
|
782
810
|
"no-restricted-syntax": [
|
|
783
811
|
"error",
|
|
784
812
|
NO_SATISFIES,
|
|
813
|
+
NO_AS_CONST,
|
|
785
814
|
...RESTRICTED_SYNTAX,
|
|
786
815
|
...SINGLE_OBJECT_PARAMETER,
|
|
787
816
|
],
|
|
@@ -886,6 +915,7 @@ const config = [
|
|
|
886
915
|
rules: {
|
|
887
916
|
"no-restricted-syntax": [
|
|
888
917
|
"error",
|
|
918
|
+
NO_AS_CONST,
|
|
889
919
|
...RESTRICTED_SYNTAX,
|
|
890
920
|
...SINGLE_OBJECT_PARAMETER,
|
|
891
921
|
],
|
|
@@ -898,6 +928,7 @@ const config = [
|
|
|
898
928
|
"no-restricted-syntax": [
|
|
899
929
|
"error",
|
|
900
930
|
NO_SATISFIES,
|
|
931
|
+
NO_AS_CONST,
|
|
901
932
|
...RESTRICTED_SYNTAX,
|
|
902
933
|
],
|
|
903
934
|
},
|
|
@@ -1078,13 +1109,13 @@ Names are full English words: `btn` must be `button`, `e` must be `error` or `ev
|
|
|
1078
1109
|
|
|
1079
1110
|
The `!` operator tells the compiler a value exists without checking. Check it instead.
|
|
1080
1111
|
|
|
1081
|
-
### `no-restricted-syntax`: type first, never `satisfies`
|
|
1112
|
+
### `no-restricted-syntax`: type first, never `satisfies` or `as const`
|
|
1082
1113
|
|
|
1083
|
-
A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. The rule lists live in `RESTRICTED_SYNTAX` and `
|
|
1114
|
+
A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. `as const` is an error everywhere, story files included: see [No `as const`](/docs/Standards/readable-code#no-as-const). The rule lists live in `RESTRICTED_SYNTAX`, `NO_SATISFIES` and `NO_AS_CONST` at the top of each config, so story files use every other restriction without repeating it. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
|
|
1084
1115
|
|
|
1085
1116
|
### `@typescript-eslint/consistent-type-assertions: never`
|
|
1086
1117
|
|
|
1087
|
-
`as` casts are errors
|
|
1118
|
+
`as` casts are errors. This rule always lets `as const` through, so `NO_AS_CONST` in `no-restricted-syntax` stops it instead. When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/docs/Standards/readable-code#no-any-no--no-unexplained-as) requires:
|
|
1088
1119
|
|
|
1089
1120
|
```ts
|
|
1090
1121
|
// eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- the API returns untyped JSON; validated by parseUser below
|
|
@@ -456,7 +456,7 @@ const getUserName = (user: any) => {
|
|
|
456
456
|
};
|
|
457
457
|
```
|
|
458
458
|
|
|
459
|
-
`as const` is
|
|
459
|
+
`as const` is never used either: see [No `as const`](#no-as-const). See the [ESLint configuration](/docs/Standards/eslint#typescript-eslintconsistent-type-assertions-never) for how to record the reason for a cast.
|
|
460
460
|
|
|
461
461
|
---
|
|
462
462
|
|
|
@@ -595,6 +595,35 @@ ESLint reports `satisfies` as an error.
|
|
|
595
595
|
|
|
596
596
|
---
|
|
597
597
|
|
|
598
|
+
### No `as const` {#no-as-const}
|
|
599
|
+
|
|
600
|
+
**Give a value a real type where it is declared, never `as const`.** `as const` makes the value the source of truth and leaves TypeScript to work out the type. A written type is the contract a reader sees first, and the value is checked against it.
|
|
601
|
+
|
|
602
|
+
```ts
|
|
603
|
+
// ✅ Good — the exact values are in the type
|
|
604
|
+
type RoleType = "admin" | "editor";
|
|
605
|
+
|
|
606
|
+
interface AccessType {
|
|
607
|
+
roles: readonly RoleType[];
|
|
608
|
+
}
|
|
609
|
+
|
|
610
|
+
const ACCESS: AccessType = { roles: ["admin", "editor"] };
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
```ts
|
|
614
|
+
// ❌ Bad — the type is worked out from the value
|
|
615
|
+
const ACCESS = { roles: ["admin", "editor"] } as const;
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
- **A written type widens each value to the type.** When the code needs the exact values, put them in the type, as `RoleType` does above.
|
|
619
|
+
- **A constant's list is `readonly` in its type**, so nothing changes it by accident. Lists in props, parameters and state need not be.
|
|
620
|
+
- **A list that must hold every value** is checked with a `Record` over the values' type, or with a test. A typed list checks that each item is a real value, not that none is missing.
|
|
621
|
+
- **`r` and `s` are never typed by hand.** Their types are read from their values (`keyof typeof r.plans`), and they need no `as const` either.
|
|
622
|
+
|
|
623
|
+
ESLint reports `as const` as an error. If one is genuinely unavoidable, disable the rule on that line with the reason, as for a cast: `// eslint-disable-next-line no-restricted-syntax -- <reason>`.
|
|
624
|
+
|
|
625
|
+
---
|
|
626
|
+
|
|
598
627
|
## Error messages say what happened and what to do
|
|
599
628
|
|
|
600
629
|
An error message is read by someone in the middle of a problem. Tell them what went wrong and how to fix it.
|
|
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
|
|
|
5
5
|
|
|
6
6
|
# Working with Agents
|
|
7
7
|
|
|
8
|
-
> How an AI agent links a project's work, reports on it
|
|
8
|
+
> How an AI agent links a project's work, reports on it, asks before committing and tells the person about its decisions. The GitHub repo, the Linear project, the status circles, asking before every commit and push, and being told about decisions are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all five every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
9
9
|
|
|
10
10
|
Whatever the project chooses is written into the **Project workflow** section of its `AGENTS.md`, from the [template](/docs/templates#agents), so every agent in the project follows it.
|
|
11
11
|
|
|
@@ -45,3 +45,7 @@ Optional. An agent reports the state of every ticket or piece of work as one lin
|
|
|
45
45
|
## Ask before committing
|
|
46
46
|
|
|
47
47
|
Optional. Setup asks: "Would you like AI to ask you before every commit and push to git?" A yes is written under **Who commits** in Project workflow: ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only. A no means nothing is written, and the agent uses its own judgement.
|
|
48
|
+
|
|
49
|
+
## Told about decisions
|
|
50
|
+
|
|
51
|
+
Optional. Setup asks: "Would you like AI to tell you about each coding decision it makes that the code standards do not cover?" The code standards are the base, and the agent builds freely from them, so it makes many calls of its own. A person who reads the code may want to hear each one; a person who does not may not care. A yes is written under **Decisions** in Project workflow: the agent lists each such decision in its summary at the end of the task. A no means nothing is written, and the agent decides without reporting.
|
|
@@ -301,7 +301,7 @@ Add the export to `utils/index.ts` whenever you add a function.
|
|
|
301
301
|
|
|
302
302
|
## 🔤 Constants: `r`, `s`, numbers, noData, animation, artwork and class names {#constants}
|
|
303
303
|
|
|
304
|
-
Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files.
|
|
304
|
+
Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files. Internal strings people never see are the one exception: see [`s`: strings](#s-strings).
|
|
305
305
|
|
|
306
306
|
```text
|
|
307
307
|
lib/constants/
|
|
@@ -315,18 +315,20 @@ lib/constants/
|
|
|
315
315
|
└── index.ts # Exports all of them
|
|
316
316
|
```
|
|
317
317
|
|
|
318
|
-
**These seven files are the only ones.** Each is one file, never split by topic
|
|
318
|
+
**These seven files are the only ones.** Each is one file, never split by topic. `routes.ts`, `strings.ts`, `numbers.ts` and `index.ts` exist from the start; the other four are created only once the project has something to put in them.
|
|
319
319
|
|
|
320
320
|
| A value that is… | Goes in |
|
|
321
321
|
| ----------------------------------------------------------- | ------------------- |
|
|
322
322
|
| A link | `r` in `routes.ts` |
|
|
323
|
-
| Text
|
|
323
|
+
| Text people see or hear | `s` in `strings.ts` |
|
|
324
324
|
| A single number with one job | `numbers.ts` |
|
|
325
325
|
| Fake data shaped like a real response | `noData.ts` |
|
|
326
326
|
| A group of values that together say how something moves | `animation.ts` |
|
|
327
327
|
| A group of values that together say what is drawn and where | `artwork.ts` |
|
|
328
328
|
| A Tailwind class string used by more than one file | `classNames.ts` |
|
|
329
329
|
|
|
330
|
+
**This table is the base, and where each value goes is the project's call.** The table says what each file is for, not where every value in every project goes. The project reads its own values, decides which file each one belongs in, and keeps that choice the same across the codebase. A value that fits none of them goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, where the project records why. It is a coding decision, so the work carries on without waiting for a yes.
|
|
331
|
+
|
|
330
332
|
A file outside the folder imports everything it needs in one line:
|
|
331
333
|
|
|
332
334
|
```tsx
|
|
@@ -355,7 +357,7 @@ export const r = {
|
|
|
355
357
|
|
|
356
358
|
### `s`: strings
|
|
357
359
|
|
|
358
|
-
**`s` holds every piece of
|
|
360
|
+
**`s` holds every piece of text people see or hear**: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
|
|
359
361
|
|
|
360
362
|
```ts title="lib/constants/strings.ts"
|
|
361
363
|
export const s = {
|
|
@@ -369,6 +371,7 @@ export const s = {
|
|
|
369
371
|
|
|
370
372
|
- **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
|
|
371
373
|
- **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
|
|
374
|
+
- **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. The code is never pulled apart to move them into `lib/constants/`.
|
|
372
375
|
|
|
373
376
|
### A list of items with links
|
|
374
377
|
|
|
@@ -399,24 +402,24 @@ export const r = {
|
|
|
399
402
|
|
|
400
403
|
**Write each key out by name** when you mean one item: `r.plans.starter`, never `r.plans[planId]`. A reader can see exactly which words and which link each line uses.
|
|
401
404
|
|
|
402
|
-
**Inside a loop over the list, look each item up by its key.** A loop cannot name its items, so it reads `r` and `s` with the item's
|
|
405
|
+
**Inside a loop over the list, look each item up by its key.** A loop cannot name its items, so it reads `r` and `s` with the item's key, typed from `r` itself:
|
|
403
406
|
|
|
404
407
|
```ts title="lib/types/index.ts"
|
|
405
|
-
import type { r } from "@/lib/constants";
|
|
408
|
+
import type { r } from "@/lib/constants/routes";
|
|
406
409
|
|
|
407
|
-
export type
|
|
410
|
+
export type PlanIdType = keyof typeof r.plans;
|
|
408
411
|
```
|
|
409
412
|
|
|
410
|
-
```tsx
|
|
411
|
-
{
|
|
412
|
-
<Link key={
|
|
413
|
-
{s.
|
|
413
|
+
```tsx
|
|
414
|
+
{planIds.map((planId) => (
|
|
415
|
+
<Link key={planId} href={r.plans[planId]}>
|
|
416
|
+
{s.plans[planId].action}
|
|
414
417
|
</Link>
|
|
415
418
|
))}
|
|
416
419
|
```
|
|
417
420
|
|
|
418
|
-
- **The type comes from `r`**, so a missing or misspelt
|
|
419
|
-
- **No separate lookup objects
|
|
421
|
+
- **The type comes from `r`**, so a missing or misspelt key fails the type check.
|
|
422
|
+
- **No separate lookup objects** that map a key to its link. `r` already is that lookup: a second one is a copy that drifts out of step.
|
|
420
423
|
|
|
421
424
|
### noData: stand-in data for local development
|
|
422
425
|
|
|
@@ -460,75 +463,130 @@ const insights =
|
|
|
460
463
|
export const COOKIE_DURATION_DAYS = 30;
|
|
461
464
|
export const MAXIMUM_RETRY_ATTEMPTS = 3;
|
|
462
465
|
export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
|
|
463
|
-
export const TOOLTIP_SIDE_OFFSET_PIXELS = 8;
|
|
464
466
|
```
|
|
465
467
|
|
|
466
468
|
- **One file, never split by topic.** `numbers.ts` can run past 300 lines, like `r` and `s`.
|
|
467
|
-
- **Loose numbers only.** A number that only means something beside other values
|
|
469
|
+
- **Loose numbers only.** A number that only means something beside other values stays inside its object in `animation.ts` or `artwork.ts`. It is never lifted out into `numbers.ts`.
|
|
468
470
|
- **Config files and scripts outside the app**, such as `eslint.config.mjs`, keep their numbers at the top of the file: they are not part of the app and do not import from it.
|
|
469
471
|
- **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
|
|
470
472
|
|
|
471
473
|
### Animation: how things move
|
|
472
474
|
|
|
473
|
-
**`animation.ts` holds every object that says how
|
|
475
|
+
**`animation.ts` holds every object that says how and when something moves.**
|
|
474
476
|
|
|
475
477
|
```ts title="lib/constants/animation.ts"
|
|
476
|
-
export const
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
{ degrees: 12, seconds: 0.6 },
|
|
481
|
-
{ degrees: -8, seconds: 0.4 },
|
|
482
|
-
],
|
|
483
|
-
snapSeconds: 0.2,
|
|
478
|
+
export const ENTRANCE_ANIMATION = {
|
|
479
|
+
delaySeconds: 0.1,
|
|
480
|
+
durationSeconds: 0.4,
|
|
481
|
+
offsetPixels: 24,
|
|
484
482
|
};
|
|
485
|
-
|
|
486
|
-
export const REDUCED_MOTION_QUERY =
|
|
487
|
-
"(prefers-reduced-motion: reduce)";
|
|
488
483
|
```
|
|
489
484
|
|
|
490
|
-
- **Each object stays whole.**
|
|
491
|
-
- **
|
|
492
|
-
- **Put the unit in the key**: `
|
|
485
|
+
- **Each object stays whole.** Values that only mean something together stay in one object, named by their keys. Never lift its numbers out into `numbers.ts`.
|
|
486
|
+
- **Values the animation library reads are not text on screen**, so they stay in the object, never in `s`.
|
|
487
|
+
- **Put the unit in the key**: `durationSeconds`, `offsetPixels`.
|
|
488
|
+
- **Media queries the animation reads stay in its object**, such as `reducedMotionQuery: "(prefers-reduced-motion: reduce)"`. They are read by code, not CSS, so they never move to `globals.css`.
|
|
493
489
|
|
|
494
490
|
### Artwork: what is drawn and where
|
|
495
491
|
|
|
496
|
-
**`artwork.ts` holds every object that says what is drawn
|
|
492
|
+
**`artwork.ts` holds every object that says what is drawn, where it ends up, and how it is grouped.** Where something ends up is artwork; how and when it gets there is animation.
|
|
497
493
|
|
|
498
494
|
```ts title="lib/constants/artwork.ts"
|
|
499
|
-
export const
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
{ image: "/images/backdrop/tileTwo.webp", x: 480, y: 0 },
|
|
504
|
-
];
|
|
495
|
+
export const ILLUSTRATION_LAYOUT = {
|
|
496
|
+
heightPixels: 600,
|
|
497
|
+
widthPixels: 800,
|
|
498
|
+
};
|
|
505
499
|
```
|
|
506
500
|
|
|
507
501
|
- **Each object stays whole**, the same as in `animation.ts`.
|
|
508
|
-
- **
|
|
502
|
+
- **Drawing data the code reads goes here.** A static drawing that nothing reads goes in an `.svg` file in `public/` or in an icon component.
|
|
509
503
|
|
|
510
504
|
### Class names shared between files
|
|
511
505
|
|
|
512
|
-
**`classNames.ts` holds
|
|
506
|
+
**`classNames.ts` holds Tailwind class names that more than one file uses**: a single class string, or a set of them keyed by variant.
|
|
513
507
|
|
|
514
508
|
```ts title="lib/constants/classNames.ts"
|
|
515
|
-
export const
|
|
516
|
-
"rounded-2xl border border-border bg-card
|
|
509
|
+
export const SURFACE_CLASS_NAME =
|
|
510
|
+
"rounded-2xl border border-border bg-card";
|
|
517
511
|
```
|
|
518
512
|
|
|
519
513
|
- **Make a component first.** A class string repeated across files usually means a component is missing, and the component is what makes the styling reusable. Use `classNames.ts` only when a component cannot hold the classes and they still repeat, such as when they go on different elements.
|
|
520
514
|
- **A class name used in one file stays inline in that file.**
|
|
521
|
-
- **Name each export after what it styles, ending in `_CLASS_NAME
|
|
515
|
+
- **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
|
|
522
516
|
|
|
523
|
-
###
|
|
517
|
+
### Types for constants {#types-for-constants}
|
|
518
|
+
|
|
519
|
+
**Every constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand.
|
|
520
|
+
|
|
521
|
+
```ts title="lib/types/animation.ts"
|
|
522
|
+
export interface EntranceAnimationType {
|
|
523
|
+
delaySeconds: number;
|
|
524
|
+
durationSeconds: number;
|
|
525
|
+
offsetPixels: number;
|
|
526
|
+
}
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
```ts title="lib/constants/animation.ts"
|
|
530
|
+
import type { EntranceAnimationType } from "@/lib/types";
|
|
531
|
+
|
|
532
|
+
export const ENTRANCE_ANIMATION: EntranceAnimationType = {
|
|
533
|
+
delaySeconds: 0.1,
|
|
534
|
+
durationSeconds: 0.4,
|
|
535
|
+
offsetPixels: 24,
|
|
536
|
+
};
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
- **Types live in `lib/types/`, in files named by topic**, such as `animation.ts` and `artwork.ts`. A types file is not exempt from the 300-line limit: split it by topic when it grows.
|
|
540
|
+
- **A type a constant needs lives in `lib/types/`**, with every type it depends on. Components import it from `@/lib/types`.
|
|
541
|
+
- **`lib/types/` reads a constant's type straight from its file**: `import type { r } from "@/lib/constants/routes";`, never through `@/lib/constants`. It is the one exception to importing constants in one line. `import type` is removed at build, so the two folders reading each other's types never makes a real loop.
|
|
542
|
+
- **No `as const`.** When the code needs the exact values, they go in the type, such as an id typed by its id type: `planId: PlanIdType`. Otherwise use plain `string`, `number` and `boolean`. See [No `as const`](/docs/Standards/readable-code#no-as-const).
|
|
543
|
+
- **A list gets a type for one item, and is read-only**: `ENTRANCE_STEPS: readonly EntranceStepType[]`. A list inside a list item gets its own item type too, and is read-only as well.
|
|
544
|
+
- **A map keyed by id uses `Record` over the id type**: `PLAN_BADGES: Record<PlanIdType, PlanBadgeType>`, so a missing id fails the type check. When only some ids have a value, use `Partial<Record<PlanIdType, PlanBadgeType>>`.
|
|
545
|
+
- **A lookup inside `r` or `s` that only some ids have** cannot be typed there, because `r` and `s` are never typed by hand. Declare it as a typed constant above `r` or `s` in the same file, then place it inside by name:
|
|
546
|
+
|
|
547
|
+
```ts title="lib/constants/routes.ts"
|
|
548
|
+
import type { FeatureIdType } from "@/lib/types";
|
|
549
|
+
|
|
550
|
+
const FEATURE_GUIDE_LINKS: Partial<Record<FeatureIdType, string>> = {
|
|
551
|
+
sharing: "/guides/sharing",
|
|
552
|
+
};
|
|
553
|
+
|
|
554
|
+
export const r = {
|
|
555
|
+
featureGuideLinks: FEATURE_GUIDE_LINKS,
|
|
556
|
+
};
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
The id type must not be read from the object the lookup sits in: TypeScript rejects that as a loop. Here `FeatureIdType` is `keyof typeof s.features`, read from `s`, so it can be used inside `r`.
|
|
560
|
+
|
|
561
|
+
- **A list that must hold every id** is checked with a `Record`, or with a test. A typed list checks that each item is a real id, not that none is missing.
|
|
562
|
+
- **A `.map` that builds typed items gets a return type**: `planIds.map((planId): PlanBadgeType => ({ … }))`, never a cast on a field.
|
|
563
|
+
- **When a function's `Props` and a constant share a shape**, the shape is a type in `lib/types/` and the `Props` is an alias of it: `export type GetFramePathProps = FrameShapeType;`.
|
|
564
|
+
|
|
565
|
+
### Rules {#constants-rules}
|
|
524
566
|
|
|
525
567
|
- **Named exports only:** `export const r`, `export const s`. No default exports.
|
|
526
568
|
- **Files outside `lib/constants/` import from `@/lib/constants`**, all in one import line.
|
|
527
569
|
- **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
|
|
528
570
|
- **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
|
|
529
571
|
- **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
|
|
572
|
+
- **An id lives in the object that uses it.** A value that picks which item something acts on, such as which item an animation moves to, is a key inside that object, never a loose constant of its own:
|
|
573
|
+
|
|
574
|
+
```ts
|
|
575
|
+
// Before
|
|
576
|
+
export const HIGHLIGHTED_PLAN_ID = "team";
|
|
577
|
+
export const HIGHLIGHT_ANIMATION = { durationSeconds: 0.3 };
|
|
578
|
+
|
|
579
|
+
// After
|
|
580
|
+
export const HIGHLIGHT_ANIMATION = {
|
|
581
|
+
durationSeconds: 0.3,
|
|
582
|
+
planId: "team",
|
|
583
|
+
};
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
A list of keys a loop runs over, such as `planIds` in [A list of items with links](#a-list-of-items-with-links), is not a loose id: it stays a list.
|
|
587
|
+
|
|
588
|
+
- **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`; a browser without that query misses the fallback, and the standard accepts that. **A media query the code reads is not CSS**, such as the one an animation library matches to switch motion off: it stays in its object in `animation.ts`.
|
|
530
589
|
- **All seven files can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
|
|
531
|
-
- **`lib/constants/` never imports from `lib/types/`.** `lib/types/` reads some of its types from the constants (`typeof s`), so an import the other way makes a loop. When a constant needs a type, write the type beside the constant, or read it from the constant.
|
|
532
590
|
|
|
533
591
|
---
|
|
534
592
|
|