Add code-commenting style guide TL;DR to CLAUDE.md #75

New Issue

2026-05-12T19:21:57Z

KofTwentyTwo commented

2026-05-12 19:21:57 +00:00

(Migrated from github.com)

Goal

Add a TL;DR section to CLAUDE.md so future agents auto-load the 5 principles + audit-trail rule from .planning/code-commenting-guide.md into their default context. Today, only the full guide exists at .planning/code-commenting-guide.md — agents working on unrelated tasks don't see it.

What to add

A short "Code commenting style" section in CLAUDE.md containing:
- The 5 core principles (WHY-first; audit IDs as parenthetical footnotes, not the whole comment; no stale comments; no bare TODO/FIXME without issue link; comment blocks earn their place).
- The 5 comment shapes (file opener, type docstring, method docstring, ASCII diagram, "Before you edit" invariants block, MARK dividers as TOC).
- The audit-trail rule (Plan IDs / audit references go in parens at end of the WHY-prose, never as the comment's sole content).
- A link to the full guide at .planning/code-commenting-guide.md for examples.
Add the new boundary gate scripts/check-no-stale-plan-id-comments.sh to the boundary-gates list (after the tooling issue lands).

Constraints

Do not duplicate the full guide — TL;DR only, link out for details.
Match existing CLAUDE.md section voice.

Parent epic

#64

Source

.planning/code-commenting-guide.md

## Goal Add a TL;DR section to `CLAUDE.md` so future agents auto-load the 5 principles + audit-trail rule from `.planning/code-commenting-guide.md` into their default context. Today, only the full guide exists at `.planning/code-commenting-guide.md` — agents working on unrelated tasks don't see it. ## What to add - A short "Code commenting style" section in `CLAUDE.md` containing: - The 5 core principles (WHY-first; audit IDs as parenthetical footnotes, not the whole comment; no stale comments; no bare `TODO`/`FIXME` without issue link; comment blocks earn their place). - The 5 comment shapes (file opener, type docstring, method docstring, ASCII diagram, "Before you edit" invariants block, MARK dividers as TOC). - The audit-trail rule (Plan IDs / audit references go in parens at end of the WHY-prose, never as the comment's sole content). - A link to the full guide at `.planning/code-commenting-guide.md` for examples. - Add the new boundary gate `scripts/check-no-stale-plan-id-comments.sh` to the boundary-gates list (after the tooling issue lands). ## Constraints - Do not duplicate the full guide — TL;DR only, link out for details. - Match existing CLAUDE.md section voice. ## Parent epic #64 ## Source .planning/code-commenting-guide.md

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#75