From 4573efd1dc74f73104d57769f974f0d19e2a6127 Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Sat, 27 Jun 2026 20:19:32 +0200 Subject: [PATCH] docs: keep code comments minimal Add a guideline to CLAUDE.md and AGENTS.md: comment only when the code genuinely needs explaining, not to narrate obvious lines. --- AGENTS.md | 1 + CLAUDE.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1c60687..f9019d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,6 +77,7 @@ Direct provider wiring currently lives in [src/config/directMessaging.ts](/Users - If a route also needs admin checks or rate limiting, combine `auth` with extra `middleware`. - Be careful around token response shapes and bearer auth. Browser-cookie auth mode has been removed. - Preserve existing local worktree changes unless the user explicitly asks you to clean them up. +- Keep comments minimal. Comment only when the code genuinely needs explaining (a non-obvious reason or gotcha); do not narrate what the code plainly does. ## Before You Finish A Change diff --git a/CLAUDE.md b/CLAUDE.md index 9d792fe..1f945bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,8 @@ when specifically exercising real DB behavior. (`npm run changeset`); don't hand-edit `CHANGELOG.md` or the version in `package.json`. - **No `any`** (`@typescript-eslint/no-explicit-any` is an error) and imports/exports are auto-sorted (`simple-import-sort`). +- **Comments** — keep them minimal. Comment only when the code genuinely needs explaining + (a non-obvious reason, a gotcha, an invariant). Don't narrate what the code plainly does. ### Codebase shape (where to make changes)