From 2f8da2f7d10d4f1fbb3d8dd0287fc68bba9ab4bf Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 29 May 2026 06:48:41 +0000 Subject: [PATCH 1/3] dld-implement: discourage duplicating decision context in comments Add opinionated guidance to the annotation step: default to the bare @decision annotation, don't restate the decision's rationale in code comments, and only add further comments when the code itself is non-obvious. Keeps the decision record as the single source of truth. --- .claude/skills/dld-implement/SKILL.md | 12 ++++++++++++ skills/dld-implement/SKILL.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/.claude/skills/dld-implement/SKILL.md b/.claude/skills/dld-implement/SKILL.md index a919a7e..69dd622 100644 --- a/.claude/skills/dld-implement/SKILL.md +++ b/.claude/skills/dld-implement/SKILL.md @@ -97,6 +97,18 @@ def calculate_vat(order: Order) -> Money: - Multiple decisions can annotate the same code: `// @decision(DL-012) @decision(DL-015)` - Use the `annotation_prefix` from `dld.config.yaml` (default: `@decision`) +**Keep annotations lean — the decision record is the single source of truth.** + +The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constraints, alternatives, consequences) in the decision record, *not* scattered through the code. The annotation is a pointer, not a summary. Do not let implementing a decision turn into a comment-writing exercise. + +- **Default to the bare annotation.** `// @decision(DL-012)` on its own is the norm and is usually all you need. +- **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted. +- **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y." +- **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job). +- **Match the surrounding file's comment density.** If the codebase is sparse on comments, don't introduce a wave of new ones just because you implemented a decision. + +When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record. + ### 4. Update decision records For each implemented decision: diff --git a/skills/dld-implement/SKILL.md b/skills/dld-implement/SKILL.md index 3832672..89da3a4 100644 --- a/skills/dld-implement/SKILL.md +++ b/skills/dld-implement/SKILL.md @@ -97,6 +97,18 @@ def calculate_vat(order: Order) -> Money: - Multiple decisions can annotate the same code: `// @decision(DL-012) @decision(DL-015)` - Use the `annotation_prefix` from `dld.config.yaml` (default: `@decision`) +**Keep annotations lean — the decision record is the single source of truth.** + +The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constraints, alternatives, consequences) in the decision record, *not* scattered through the code. The annotation is a pointer, not a summary. Do not let implementing a decision turn into a comment-writing exercise. + +- **Default to the bare annotation.** `// @decision(DL-012)` on its own is the norm and is usually all you need. +- **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted. +- **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y." +- **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job). +- **Match the surrounding file's comment density.** If the codebase is sparse on comments, don't introduce a wave of new ones just because you implemented a decision. + +When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record. + ### 4. Update decision records For each implemented decision: From 6dcf70c394ba94939bc05e663342d09832e443ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Utterstr=C3=B6m?= Date: Mon, 1 Jun 2026 13:29:24 +0200 Subject: [PATCH 2/3] Revise SKILL.md for decision annotation best practices Clarify guidelines on decision annotations and comments. --- .claude/skills/dld-implement/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.claude/skills/dld-implement/SKILL.md b/.claude/skills/dld-implement/SKILL.md index 69dd622..fb1cb7a 100644 --- a/.claude/skills/dld-implement/SKILL.md +++ b/.claude/skills/dld-implement/SKILL.md @@ -105,7 +105,6 @@ The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constra - **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted. - **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y." - **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job). -- **Match the surrounding file's comment density.** If the codebase is sparse on comments, don't introduce a wave of new ones just because you implemented a decision. When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record. From ee5a31e4161016e9a4f1933d0be258b4d7d07a9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jimmy=20Utterstr=C3=B6m?= Date: Mon, 1 Jun 2026 13:31:01 +0200 Subject: [PATCH 3/3] Revise commenting guidelines for decision annotations Clarified guidelines on commenting decisions in code. --- skills/dld-implement/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/dld-implement/SKILL.md b/skills/dld-implement/SKILL.md index 89da3a4..d82616f 100644 --- a/skills/dld-implement/SKILL.md +++ b/skills/dld-implement/SKILL.md @@ -105,7 +105,6 @@ The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constra - **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted. - **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y." - **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job). -- **Match the surrounding file's comment density.** If the codebase is sparse on comments, don't introduce a wave of new ones just because you implemented a decision. When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record.