CtrlK
BlogDocsLog inGet started
Tessl Logo

giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

82

Quality

82%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Risky

Do not use without reviewing

Validation failed for skills in this tile
One or more skills have errors that need to be fixed before they can move to Implementation and Discovery review.
Overview
Quality
Evals
Security
Files

update-guidelines.mdplugins/developer-kit-core/skills/claude-md-management/references/

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?

plugins

developer-kit-core

skills

claude-md-management

references

quality-criteria.md

templates.md

update-guidelines.md

SKILL.md

README.md

tile.json