1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
## Engineering Principles
- Never delete published software versions
- Never run sudo commands yourself, ask the user
- Use `lightpanda` when internet access is needed; run `lightpanda --help` first to get the full list of available commands and options
- Surface assumptions before building. Wrong assumptions held silently are the most common failure mode.
- Push back when warranted. The agent (or engineer) is not a yes-machine.
- Prefer the boring, obvious solution. Cleverness is expensive.
- Touch only what you're asked to touch.
- When scripting is necessary, create a python file, use inline metadata for dependencies and `uv run <script.py>`
- Stop and ask when requirements conflict. Don't guess.
- Ask if it works before commiting
- All code comments must be in English. No French comments in code.
## Implementation
- Add a few logs at the feature level (not inside every unit function).
- When possible, start with a failing test and ask for user validation before implementing the fix or feature.
- No new tests are needed during pure refactoring.
## Software Design
- Ubiquitous Language - Names matter. Ask the user when defining a new concept
- Entity - Objects having a stable identity encapsulate data and invariants
- Value Objects - Immutable, self-validating. Date, Money, ...
- Enum-to-enum conversion - Never convert one enum to another with a ternary or `if/else`. A ternary silently collapses every unhandled input value into the fallback branch, so adding a new member to the source enum compiles without error and produces a wrong result. Use an exhaustive object map typed as `Record<SourceEnum, TargetEnum>` so a new source member is a compile error until it is mapped.
## Tools
- Toujours utiliser `rg` (ripgrep) à la place de `grep` pour la recherche dans les fichiers
- Toujours utiliser `find` pour la recherche de fichiers par nom/chemin
## Feature Completion
Avant de considérer une feature comme terminée, toujours exécuter dans l'ordre :
1. Formatage du code
2. Lint (`pnpm lint` ou équivalent)
3. Build (`pnpm build` ou équivalent)
4. Tests (`pnpm test` ou équivalent sur le scope impacté)
## Testing
- Utiliser des UUID plutôt que des 'machin-id' dans les tests
## Dependency Changes
- Ne pas edit les dépendances manuellement, utiliser le package manager
1. Edit all config files in one pass
2. Run `pnpm install --lockfile-only` to update lockfile
3. Run `pnpm why <package>` to verify removal
4. Run tests to confirm nothing broke
## Documentation
- After finishing a new feature, add a one line entry to the README explaining the feature for a user.
## Data
Filling CSV may be easier using cat to append a line at the end, than to edit the file.
You can add data at the end, and sort it later if needed.
## UI Validation
- Always validate the UI visually before finishing a task (fetch the page via
lightpanda or check the rendered HTML/CSS output to verify layout is
correct).
|
