claude-plugins-official/plugins/claude-md-management/skills/claude-md-improver/references/update-guidelines.md

CLAUDE.md Update Guidelines

Core Principle

Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.

What TO Add

1. Commands/Workflows Discovered

## Build

`npm run build:prod` - Full production build with optimization
`npm run build:dev` - Fast dev build (no minification)

Why: Saves future sessions from discovering these again.

2. Gotchas and Non-Obvious Patterns

## Gotchas

- Tests must run sequentially (`--runInBand`) due to shared DB state
- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch

Why: Prevents repeating debugging sessions.

3. Package Relationships

## Dependencies

The `auth` module depends on `crypto` being initialized first.
Import order matters in `src/bootstrap.ts`.

Why: Architecture knowledge that isn't obvious from code.

4. Testing Approaches That Worked

## Testing

For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
Mocking: Factory functions in `tests/factories/` (not inline mocks)

Why: Establishes patterns that work.

5. Configuration Quirks

## Config

- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
- Redis connection requires `?family=0` suffix for IPv6

Why: Environment-specific knowledge.

What NOT to Add

1. Obvious Code Info

Bad:

The `UserService` class handles user operations.

The class name already tells us this.

2. Generic Best Practices

Bad:

Always write tests for new features.
Use meaningful variable names.

This is universal advice, not project-specific.

3. One-Off Fixes

Bad:

We fixed a bug in commit abc123 where the login button didn't work.

Won't recur; clutters the file.

4. Verbose Explanations

Bad:

The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
an open standard (RFC 7519) that defines a compact and self-contained
way for securely transmitting information between parties as a JSON
object. In our implementation, we use the HS256 algorithm which...

Good:

Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.

Diff Format for Updates

For each suggested change:

1. Identify the File

File: ./CLAUDE.md
Section: Commands (new section after ## Architecture)

2. Show the Change

 ## Architecture
 ...

+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |

3. Explain Why

Why this helps: The build commands weren't documented, causing confusion about how to run the project. This saves future sessions from needing to inspect package.json.

Validation Checklist

Before finalizing an update, verify:

• Each addition is project-specific
• No generic advice or obvious info
• Commands are tested and work
• File paths are accurate
• Would a new Claude session find this helpful?
• Is this the most concise way to express the info?