feat(memory): introduce .claude/{tasks,memory,audits}/ governance layout
Move tasks/ into .claude/tasks/ and create .claude/memory/ with 5 persistent registries (decisions/learnings/blockers/journal/evals) plus .claude/audits/ for audit reports. Also seed templates/memory/ for onboarder to copy into user projects. - tasks/TODO.md, tasks/rtk-upstream-issue.md → .claude/tasks/ - tasks/LESSONS.md deleted (empty template; superseded by learnings.md) - .claude/memory/: 5 append-only registries with YAML schema + seed entries - templates/memory/: 5 empty-index templates for new projects Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bastien
parent
6f5f4fe5b5
commit
892de288fe
36
.claude/memory/blockers.md
Normal file
36
.claude/memory/blockers.md
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
type: blockers_registry
|
||||
entry_prefix: BLK
|
||||
schema:
|
||||
id: BLK-XXX
|
||||
date: YYYY-MM-DD
|
||||
friction: string (what was blocked)
|
||||
real_cause: string (root cause, not symptom)
|
||||
solution: string (workaround or fix)
|
||||
status: [open | resolved | upstream]
|
||||
rules:
|
||||
- Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on".
|
||||
- Link to upstream issue / PR / commit when applicable.
|
||||
- If cause is a bug in a dependency, set status upstream with a pointer to the tracker.
|
||||
---
|
||||
|
||||
# Blockers registry (BLK)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Friction | Status |
|
||||
|----|------|---------|--------|
|
||||
| BLK-001 | 2026-04-22 | `rtk curl` breaks JSON pipelines | upstream |
|
||||
|
||||
---
|
||||
|
||||
## BLK-001 — `rtk curl` returns compressed schema in pipes
|
||||
|
||||
- **Date** : 2026-04-22
|
||||
- **Friction** : toute pipeline `rtk curl ... | python -c "json.load(sys.stdin)"` (ou `jq`, `awk`) échoue sans message clair.
|
||||
- **Cause réelle** : `rtk curl` auto-compresse stdout indépendamment du TTY — documenté dans `.claude/tasks/rtk-upstream-issue.md`.
|
||||
- **Solution** :
|
||||
- Workaround court terme : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`.
|
||||
- Workaround alternatif : utiliser `rtk proxy`.
|
||||
- Fix upstream : issue reportée, voir `.claude/tasks/rtk-upstream-issue.md`.
|
||||
- **Statut** : upstream (bug chez `rtk`, workaround appliqué).
|
||||
51
.claude/memory/decisions.md
Normal file
51
.claude/memory/decisions.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
type: decisions_registry
|
||||
entry_prefix: BDR
|
||||
schema:
|
||||
id: BDR-XXX
|
||||
date: YYYY-MM-DD
|
||||
title: string (<= 80 chars)
|
||||
decision: string (what was chosen)
|
||||
why: string (motivation, context)
|
||||
alternatives: list of strings (what was rejected + why)
|
||||
status: [proposed | accepted | deprecated | superseded]
|
||||
supersedes: BDR-XXX (optional)
|
||||
rules:
|
||||
- Append-only. Never rewrite past entries - add a new one with status superseded if needed.
|
||||
- One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact.
|
||||
- Capture why more carefully than what - the what rots, the why lasts.
|
||||
---
|
||||
|
||||
# Decisions registry (BDR)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Title | Status |
|
||||
|----|------|-------|--------|
|
||||
| BDR-001 | 2026-04-22 | --help helper uniforme via hook post-start (option C) | accepted |
|
||||
| BDR-002 | 2026-04-23 | Restructurer tasks/ + memory + audits sous .claude/ | accepted |
|
||||
|
||||
---
|
||||
|
||||
## BDR-001 — --help helper uniforme via hook post-start (option C)
|
||||
|
||||
- **Date** : 2026-04-22
|
||||
- **Statut** : accepted
|
||||
- **Décision** : tous les skills exposent `--help` via un snippet partagé injecté par le session-start hook, plutôt que dupliquer le helper dans chaque SKILL.md.
|
||||
- **Pourquoi** : 25+ skills, maintenir le même helper dans chaque fichier = drift garanti. Un point d'injection = une seule source de vérité.
|
||||
- **Alternatives rejetées** :
|
||||
- Option A (copier le helper dans chaque SKILL.md) — refusée : entropie de maintenance.
|
||||
- Option B (wrapper externe `/help <skill>`) — refusée : casse l'expérience "une commande = un skill".
|
||||
- **Référence** : commit 3968a29.
|
||||
|
||||
## BDR-002 — Restructurer tasks/ + memory + audits sous .claude/
|
||||
|
||||
- **Date** : 2026-04-23
|
||||
- **Statut** : accepted
|
||||
- **Décision** : migrer `./tasks/` vers `.claude/tasks/`, créer `.claude/memory/` (5 registres BDR/LRN/BLK/journal/EVAL) et `.claude/audits/` pour les fichiers AUDIT_*. Adapter skills/agents/CLAUDE.md. Intégrer un rituel de capitalisation dans les skills de complétion (ship-feature, feat, bugfix, hotfix, commit-change) + créer un skill `/close` pour le rituel de fin de session.
|
||||
- **Pourquoi** : regrouper tout le méta-projet (config IA + tâches + mémoire + audits) sous `.claude/` isole la gouvernance Claude du code réel. Alignement sur la doc officielle Claude Code memory. Sans intégration dans les skills, les registres resteraient vides (aspirational text).
|
||||
- **Alternatives rejetées** :
|
||||
- Laisser `./tasks/` à la racine — refusée : encombre le repo, mélange signal code / signal gouvernance.
|
||||
- Utiliser `.claude/agent-memory/` pour tout — refusée : `agent-memory/` a un rôle distinct (déjà utilisé par d'autres outils).
|
||||
- Rituel uniquement en texte aspirationnel dans CLAUDE.md — refusée : zéro garantie d'exécution, les registres resteraient vides.
|
||||
- Hook `Stop` pour poser les 3 questions à chaque tour — refusée : trop bruyant.
|
||||
34
.claude/memory/evals.md
Normal file
34
.claude/memory/evals.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
type: evals_registry
|
||||
entry_prefix: EVAL
|
||||
schema:
|
||||
id: EVAL-XXX
|
||||
date: YYYY-MM-DD
|
||||
output: string (what was produced)
|
||||
method: string (how it was evaluated - manual read, test, benchmark, user feedback)
|
||||
anomalies: list of strings (what was wrong, missing, surprising)
|
||||
action: [keep | correct | deprecate]
|
||||
rules:
|
||||
- Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code).
|
||||
- Action keep - the output is fit for purpose as-is.
|
||||
- Action correct - needs revision; capture what.
|
||||
- Action deprecate - the approach itself is flawed; link to the decision that replaces it.
|
||||
---
|
||||
|
||||
# Evals registry (EVAL)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Output | Action |
|
||||
|----|------|--------|--------|
|
||||
| EVAL-001 | 2026-04-23 | Plan de restructuration .claude/ (STEP 2 de ship-feature) | keep |
|
||||
|
||||
---
|
||||
|
||||
## EVAL-001 — Plan de restructuration `.claude/`
|
||||
|
||||
- **Date** : 2026-04-23
|
||||
- **Output** : plan 21 tâches pour migrer `tasks/` vers `.claude/tasks/` + créer `.claude/memory/` + `.claude/audits/` + intégrer CAPITALIZE dans 5 skills + créer `/close`.
|
||||
- **Méthode** : relecture manuelle des 5 skills/agents impactés, vérification que rtk est path-agnostic, symlink `~/.claude/CLAUDE.md` → projet confirmé (un seul fichier à éditer). Radical-honesty check sur le ritual "session-close" : confirmé comme aspirationnel sans intégration dans les skills → scope élargi à Option D.
|
||||
- **Anomalies** : aucune bloquante. Note : `tasks/LESSONS.md` était vide (101B, juste un header) — migration vers `learnings.md` symbolique.
|
||||
- **Action** : keep — plan validé, prêt pour exécution.
|
||||
19
.claude/memory/journal.md
Normal file
19
.claude/memory/journal.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
type: journal
|
||||
schema:
|
||||
entry: one date heading per working session
|
||||
body: 3-5 lines max - what was done, decided, blocked
|
||||
rules:
|
||||
- One heading per date (YYYY-MM-DD), not per session.
|
||||
- Append at the end. Never edit past entries.
|
||||
- Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only.
|
||||
---
|
||||
|
||||
# Journal
|
||||
|
||||
## 2026-04-23
|
||||
|
||||
- Restructuré l'arborescence : `tasks/` → `.claude/tasks/`, créé `.claude/memory/` (5 registres) + `.claude/audits/`.
|
||||
- Adapté CLAUDE.md + skills `onboard`, `init-project` + agent `onboarder` + `lib/project-archetypes/dotfiles-meta.md`.
|
||||
- Ajouté un step CAPITALIZE dans `ship-feature`, `bugfix`, `hotfix`, `feat`, `commit-change` + créé skill `/close` pour rituel de fin de session.
|
||||
- Décision BDR-002 actée.
|
||||
32
.claude/memory/learnings.md
Normal file
32
.claude/memory/learnings.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
type: learnings_registry
|
||||
entry_prefix: LRN
|
||||
schema:
|
||||
id: LRN-XXX
|
||||
date: YYYY-MM-DD
|
||||
pattern: string (what was observed, abstracted)
|
||||
context: string (where/when it happened - concrete)
|
||||
future_application: string (when to recall this)
|
||||
rules:
|
||||
- Capture learnings that apply beyond the current task.
|
||||
- Abstract from the incident - the pattern is what is reusable, not the one-shot fact.
|
||||
- Link to source (commit, file, PR) when possible.
|
||||
- Replaces the previous LESSONS.md format. Old file was empty - no content to migrate.
|
||||
---
|
||||
|
||||
# Learnings registry (LRN)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Pattern | Applies to |
|
||||
|----|------|---------|------------|
|
||||
| LRN-001 | 2026-04-22 | `rtk` shape-compression breaks pipes | any pipeline chaining `rtk curl/cat/read` into `jq`, `python -c`, `awk` |
|
||||
|
||||
---
|
||||
|
||||
## LRN-001 — `rtk` shape-compression breaks downstream parsers
|
||||
|
||||
- **Date** : 2026-04-22
|
||||
- **Pattern** : quand un outil de tracking (`rtk`) intercepte stdout et retourne une représentation schématisée/compressée au lieu du payload brut, tout parseur en aval casse silencieusement — parce que l'utilisateur (ou le LLM) ne voit jamais la sortie `rtk`, seulement l'erreur du parseur.
|
||||
- **Contexte** : `rtk curl` remplace la sortie JSON brute par une version tokenisée, indépendamment du TTY vs pipe. Les hooks Claude Code réécrivent `curl` → `rtk curl` automatiquement, donc impossible à prévoir sans connaître le hook.
|
||||
- **Application future** : pour tout outil qui auto-réécrit des commandes standard, vérifier explicitement le comportement en pipe. Workaround documenté : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`, ou `rtk proxy`. Voir `BLK-001`.
|
||||
@ -1,4 +0,0 @@
|
||||
# Lessons
|
||||
|
||||
| Date | What went wrong | Rule to avoid it |
|
||||
|------|----------------|-----------------|
|
||||
34
templates/memory/blockers.md
Normal file
34
templates/memory/blockers.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
type: blockers_registry
|
||||
entry_prefix: BLK
|
||||
schema:
|
||||
id: BLK-XXX
|
||||
date: YYYY-MM-DD
|
||||
friction: string (what was blocked)
|
||||
real_cause: string (root cause, not symptom)
|
||||
solution: string (workaround or fix)
|
||||
status: [open | resolved | upstream]
|
||||
rules:
|
||||
- Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on".
|
||||
- Link to upstream issue / PR / commit when applicable.
|
||||
- If cause is a bug in a dependency, set status upstream with a pointer to the tracker.
|
||||
---
|
||||
|
||||
# Blockers registry (BLK)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Friction | Status |
|
||||
|----|------|---------|--------|
|
||||
|
||||
<!-- Append entries below. Template:
|
||||
|
||||
## BLK-XXX - <friction>
|
||||
|
||||
- **Date** : YYYY-MM-DD
|
||||
- **Friction** : <ce qui était bloqué>
|
||||
- **Cause réelle** : <cause racine>
|
||||
- **Solution** : <workaround ou fix>
|
||||
- **Statut** : open | resolved | upstream
|
||||
|
||||
-->
|
||||
39
templates/memory/decisions.md
Normal file
39
templates/memory/decisions.md
Normal file
@ -0,0 +1,39 @@
|
||||
---
|
||||
type: decisions_registry
|
||||
entry_prefix: BDR
|
||||
schema:
|
||||
id: BDR-XXX
|
||||
date: YYYY-MM-DD
|
||||
title: string (<= 80 chars)
|
||||
decision: string (what was chosen)
|
||||
why: string (motivation, context)
|
||||
alternatives: list of strings (what was rejected + why)
|
||||
status: [proposed | accepted | deprecated | superseded]
|
||||
supersedes: BDR-XXX (optional)
|
||||
rules:
|
||||
- Append-only. Never rewrite past entries - add a new one with status superseded if needed.
|
||||
- One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact.
|
||||
- Capture why more carefully than what - the what rots, the why lasts.
|
||||
---
|
||||
|
||||
# Decisions registry (BDR)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Title | Status |
|
||||
|----|------|-------|--------|
|
||||
|
||||
<!-- Append entries below. Template:
|
||||
|
||||
## BDR-XXX - <titre>
|
||||
|
||||
- **Date** : YYYY-MM-DD
|
||||
- **Statut** : proposed | accepted | deprecated | superseded
|
||||
- **Décision** : <ce qui a été choisi>
|
||||
- **Pourquoi** : <motivation>
|
||||
- **Alternatives rejetées** :
|
||||
- Option A - <raison du rejet>
|
||||
- Option B - <raison du rejet>
|
||||
- **Référence** : <commit / PR / fichier>
|
||||
|
||||
-->
|
||||
35
templates/memory/evals.md
Normal file
35
templates/memory/evals.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
type: evals_registry
|
||||
entry_prefix: EVAL
|
||||
schema:
|
||||
id: EVAL-XXX
|
||||
date: YYYY-MM-DD
|
||||
output: string (what was produced)
|
||||
method: string (how it was evaluated - manual read, test, benchmark, user feedback)
|
||||
anomalies: list of strings (what was wrong, missing, surprising)
|
||||
action: [keep | correct | deprecate]
|
||||
rules:
|
||||
- Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code).
|
||||
- Action keep - the output is fit for purpose as-is.
|
||||
- Action correct - needs revision; capture what.
|
||||
- Action deprecate - the approach itself is flawed; link to the decision that replaces it.
|
||||
---
|
||||
|
||||
# Evals registry (EVAL)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Output | Action |
|
||||
|----|------|--------|--------|
|
||||
|
||||
<!-- Append entries below. Template:
|
||||
|
||||
## EVAL-XXX - <output>
|
||||
|
||||
- **Date** : YYYY-MM-DD
|
||||
- **Output** : <ce qui a été produit>
|
||||
- **Méthode** : <comment cela a été évalué>
|
||||
- **Anomalies** : <ce qui est faux, manquant, surprenant>
|
||||
- **Action** : keep | correct | deprecate
|
||||
|
||||
-->
|
||||
22
templates/memory/journal.md
Normal file
22
templates/memory/journal.md
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
type: journal
|
||||
schema:
|
||||
entry: one date heading per working session
|
||||
body: 3-5 lines max - what was done, decided, blocked
|
||||
rules:
|
||||
- One heading per date (YYYY-MM-DD), not per session.
|
||||
- Append at the end. Never edit past entries.
|
||||
- Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only.
|
||||
---
|
||||
|
||||
# Journal
|
||||
|
||||
<!-- Append new date-heading entries below. Template:
|
||||
|
||||
## YYYY-MM-DD
|
||||
|
||||
- <ligne 1>
|
||||
- <ligne 2>
|
||||
- <ligne 3-5 max>
|
||||
|
||||
-->
|
||||
32
templates/memory/learnings.md
Normal file
32
templates/memory/learnings.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
type: learnings_registry
|
||||
entry_prefix: LRN
|
||||
schema:
|
||||
id: LRN-XXX
|
||||
date: YYYY-MM-DD
|
||||
pattern: string (what was observed, abstracted)
|
||||
context: string (where/when it happened - concrete)
|
||||
future_application: string (when to recall this)
|
||||
rules:
|
||||
- Capture learnings that apply beyond the current task.
|
||||
- Abstract from the incident - the pattern is what is reusable, not the one-shot fact.
|
||||
- Link to source (commit, file, PR) when possible.
|
||||
---
|
||||
|
||||
# Learnings registry (LRN)
|
||||
|
||||
## Index
|
||||
|
||||
| ID | Date | Pattern | Applies to |
|
||||
|----|------|---------|------------|
|
||||
|
||||
<!-- Append entries below. Template:
|
||||
|
||||
## LRN-XXX - <pattern abstrait>
|
||||
|
||||
- **Date** : YYYY-MM-DD
|
||||
- **Pattern** : <ce qui a été observé, formulé de manière réutilisable>
|
||||
- **Contexte** : <où et quand, concret>
|
||||
- **Application future** : <quand se rappeler de ceci>
|
||||
|
||||
-->
|
||||
Loading…
Reference in New Issue
Block a user