feat(context): Context Engineering Configurator + consolidated guide (v3.34.0)
New: interactive configurator at cc.bruniaux.com/context/ that generates a personalized CLAUDE.md starter kit based on team size, stack, and current setup. Multi-step flow (profile, current state, stack, results) with maturity scoring (Level 1-5), copy-to-clipboard artifacts, localStorage persistence. Guide content: - guide/core/context-engineering.md (1,188 lines, 8 sections): context budget, 150-instruction ceiling, modular architecture, team assembly, ACE pipeline, quality measurement, context reduction techniques - examples/context-engineering/ (10 templates): assembler.ts, profile-template.yaml, skeleton-template.md, canary-check.sh, ci-drift-check.yml, eval-questions.yaml, context-budget-calculator.sh, rules/knowledge-feeding.md, rules/update-loop-retro.md - tools/context-audit-prompt.md (543 lines): 8-dimension scoring /100 Navigation: guide/README.md, machine-readable/reference.yaml (24 new entries) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
318ba915de
commit
fe28f89574
19 changed files with 3545 additions and 15 deletions
288
examples/context-engineering/skeleton-template.md
Normal file
288
examples/context-engineering/skeleton-template.md
Normal file
|
|
@ -0,0 +1,288 @@
|
|||
# CLAUDE.md — [Project Name]
|
||||
|
||||
<!--
|
||||
HOW TO USE THIS SKELETON
|
||||
|
||||
Fill in each section based on your project. Delete placeholder comments when done.
|
||||
Goal: give Claude enough context to make correct decisions without asking, while staying under 500 lines.
|
||||
|
||||
Key principles:
|
||||
- Specific beats vague: "Use zod for external input validation" beats "validate inputs"
|
||||
- Anti-patterns are as valuable as rules: tell Claude what NOT to do
|
||||
- Update after each significant session (see rules/update-loop-retro.md)
|
||||
- Run `canary-check.sh` weekly to catch drift
|
||||
-->
|
||||
|
||||
## Project Overview
|
||||
|
||||
<!--
|
||||
Write 2-3 sentences answering:
|
||||
- What does this project do?
|
||||
- Who uses it? (internal tool, public API, consumer app, etc.)
|
||||
- What's the primary language and deployment target?
|
||||
|
||||
Example:
|
||||
"A REST API that processes financial transactions for retail merchants, consumed by a Next.js
|
||||
dashboard and a React Native mobile app. Built with Node.js + TypeScript, deployed to AWS ECS.
|
||||
PCI-DSS compliance applies to all payment-adjacent code."
|
||||
-->
|
||||
|
||||
[PROJECT DESCRIPTION]
|
||||
|
||||
## Architecture
|
||||
|
||||
<!--
|
||||
Describe the shape of the system. Not a tutorial — just the decisions Claude needs to
|
||||
make correct assumptions. Diagrams are optional; prose is fine.
|
||||
|
||||
Cover:
|
||||
- Monolith or services? If services, how many and how do they communicate?
|
||||
- How is state managed (database, cache, event sourcing)?
|
||||
- Key data flow (request lifecycle, async patterns)
|
||||
- Folder structure if non-obvious
|
||||
-->
|
||||
|
||||
### Stack
|
||||
|
||||
| Layer | Technology | Version |
|
||||
|-------|-----------|---------|
|
||||
| Language | TypeScript | 5.x |
|
||||
| Runtime | Node.js | 20.x |
|
||||
| Framework | [e.g., Express, Fastify, NestJS] | x.x |
|
||||
| Database | [e.g., PostgreSQL] | x.x |
|
||||
| ORM / Query Builder | [e.g., Prisma, Drizzle, Knex] | x.x |
|
||||
| Cache | [e.g., Redis, none] | - |
|
||||
| Message Queue | [e.g., BullMQ, SQS, none] | - |
|
||||
| Frontend | [e.g., Next.js, none] | x.x |
|
||||
| Testing | [e.g., Vitest, Jest] | x.x |
|
||||
| CI/CD | [e.g., GitHub Actions] | - |
|
||||
|
||||
### Folder Structure
|
||||
|
||||
```
|
||||
src/
|
||||
[describe key directories and what belongs in each]
|
||||
[example: api/ — route handlers only, no business logic]
|
||||
[example: services/ — business logic, called by handlers]
|
||||
[example: db/ — Prisma schema, migrations, query functions]
|
||||
```
|
||||
|
||||
### Key Architectural Decisions
|
||||
|
||||
<!--
|
||||
Record the "why" behind non-obvious choices. This prevents Claude from suggesting
|
||||
alternatives that were already considered and rejected.
|
||||
|
||||
Example:
|
||||
- Repository pattern is NOT used — we use Prisma directly in services (decision: team
|
||||
familiarity, added abstraction not worth it at current scale)
|
||||
- Zod schemas are colocated with route handlers, not in a shared schemas/ directory
|
||||
-->
|
||||
|
||||
- [DECISION 1]
|
||||
- [DECISION 2]
|
||||
|
||||
## Code Standards
|
||||
|
||||
<!--
|
||||
Be specific. "Write clean code" is useless. "Use named exports only — no default exports" is actionable.
|
||||
Organize by language/domain if you have multiple.
|
||||
-->
|
||||
|
||||
### TypeScript
|
||||
|
||||
- Strict mode is enabled (`"strict": true` in tsconfig). Never use `any` — use `unknown` and narrow.
|
||||
- All public function signatures must have explicit return types.
|
||||
- Use `type` for unions and intersections, `interface` for object shapes that may be extended.
|
||||
- [ADD YOUR RULES]
|
||||
|
||||
### Naming
|
||||
|
||||
- Files: `kebab-case.ts` (e.g., `user-service.ts`, `create-order.test.ts`)
|
||||
- Classes: `PascalCase`
|
||||
- Functions and variables: `camelCase`
|
||||
- Constants: `SCREAMING_SNAKE_CASE`
|
||||
- [ADD ANY EXCEPTIONS]
|
||||
|
||||
### Error Handling
|
||||
|
||||
<!--
|
||||
Undefined behavior here causes the most inconsistency. Be explicit.
|
||||
|
||||
Example:
|
||||
- All async functions must be wrapped in try/catch at the handler boundary
|
||||
- Errors propagate up as typed error objects, never raw strings
|
||||
- Use the AppError class in src/errors.ts — never throw plain Error objects in service layer
|
||||
-->
|
||||
|
||||
- [ERROR HANDLING RULES]
|
||||
|
||||
### Comments
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- Inline comments only on non-obvious logic (never explain what the code does, only why)
|
||||
- All exported functions must have a JSDoc block with @param and @returns
|
||||
- TODO comments are not allowed in production code — open an issue instead
|
||||
-->
|
||||
|
||||
- [COMMENT RULES]
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Git Conventions
|
||||
|
||||
- Branch naming: `[type]/[short-description]` — e.g., `feat/add-refund-flow`, `fix/order-status-race`
|
||||
- Commit format: [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
- `feat:` new feature
|
||||
- `fix:` bug fix
|
||||
- `chore:` maintenance, dependency updates
|
||||
- `docs:` documentation only
|
||||
- `test:` tests only
|
||||
- `refactor:` no behavior change
|
||||
- Commits should be atomic — one logical change per commit
|
||||
- [ADD ANY EXCEPTIONS OR ADDITIONAL TYPES]
|
||||
|
||||
### PR Requirements
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- All PRs require at least one reviewer
|
||||
- CI must be green before merge
|
||||
- PR description must include "Why" not just "What"
|
||||
- Link to issue or ticket in PR body
|
||||
-->
|
||||
|
||||
- [PR RULES]
|
||||
|
||||
### Local Setup
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
[INSTALL COMMAND]
|
||||
|
||||
# Set up environment
|
||||
cp .env.example .env
|
||||
# Edit .env with your local values
|
||||
|
||||
# Run database migrations
|
||||
[MIGRATION COMMAND]
|
||||
|
||||
# Start development server
|
||||
[DEV COMMAND]
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
<!--
|
||||
Vague testing rules produce no tests. Specific rules produce correct tests.
|
||||
Tell Claude: what framework, what to test, how to structure tests, what coverage means here.
|
||||
-->
|
||||
|
||||
### Framework and Location
|
||||
|
||||
- Framework: [e.g., Vitest]
|
||||
- Test files: colocated with source (`foo.ts` → `foo.test.ts`) OR in `__tests__/` [choose one]
|
||||
- Run tests: `[TEST COMMAND]`
|
||||
- Run with coverage: `[COVERAGE COMMAND]`
|
||||
|
||||
### What Requires Tests
|
||||
|
||||
- All service layer functions (unit tests with mocked dependencies)
|
||||
- All API routes (integration tests using supertest or equivalent)
|
||||
- All utility functions that contain branching logic
|
||||
- **Not required**: pure pass-through functions, simple getters/setters, Prisma model definitions
|
||||
|
||||
### Test Structure
|
||||
|
||||
```typescript
|
||||
// Follow this pattern:
|
||||
describe('[unit under test]', () => {
|
||||
describe('[method or scenario]', () => {
|
||||
it('[expected behavior in plain English]', async () => {
|
||||
// Arrange
|
||||
// Act
|
||||
// Assert
|
||||
})
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Mocking
|
||||
|
||||
- Mock at the boundary: mock external services, never internal modules
|
||||
- [ADD YOUR MOCKING CONVENTIONS — e.g., "Use vi.mock() at file level, not inside tests"]
|
||||
|
||||
## Deployment
|
||||
|
||||
### Environments
|
||||
|
||||
| Environment | Branch | URL | Notes |
|
||||
|------------|--------|-----|-------|
|
||||
| Local | any | localhost:[PORT] | |
|
||||
| Staging | `main` | [STAGING URL] | Auto-deploys |
|
||||
| Production | [TAG/BRANCH] | [PROD URL] | Manual trigger |
|
||||
|
||||
### Deploy
|
||||
|
||||
```bash
|
||||
# Staging (auto on merge to main — no manual step needed)
|
||||
|
||||
# Production
|
||||
[DEPLOY COMMAND OR PROCESS]
|
||||
```
|
||||
|
||||
### Post-Deploy Checks
|
||||
|
||||
<!--
|
||||
Tell Claude what to verify after deploying so it can suggest this when relevant.
|
||||
|
||||
Example:
|
||||
- Check /health endpoint returns 200
|
||||
- Verify Sentry has no new errors in first 5 minutes
|
||||
- Confirm database migrations ran (check migration table)
|
||||
-->
|
||||
|
||||
- [POST-DEPLOY CHECKS]
|
||||
|
||||
## What Claude Should NOT Do
|
||||
|
||||
<!--
|
||||
This section is high-value. Anti-patterns prevent regressions and stop Claude from
|
||||
suggesting alternatives that were already rejected.
|
||||
|
||||
Be specific about the pattern AND why it's banned.
|
||||
-->
|
||||
|
||||
### Technologies Not in Use
|
||||
|
||||
- Do NOT suggest GraphQL — REST is the architectural decision for this project
|
||||
- Do NOT use [LIBRARY NAME] — replaced by [ALTERNATIVE] in [VERSION/DATE]
|
||||
- [ADD YOUR BANNED TECHNOLOGIES]
|
||||
|
||||
### Patterns to Avoid
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- Never use class components in React — functional components only
|
||||
- Never mutate request/response objects directly — use immutable patterns
|
||||
- Never use console.log in production code — use the logger at src/lib/logger.ts
|
||||
- Never hardcode environment-specific values — use process.env with validation in src/config.ts
|
||||
-->
|
||||
|
||||
- [ANTI-PATTERN 1]
|
||||
- [ANTI-PATTERN 2]
|
||||
- [ANTI-PATTERN 3]
|
||||
|
||||
### Known Problem Areas
|
||||
|
||||
<!--
|
||||
Patterns that caused production bugs or significant rework. Claude should be extra careful here.
|
||||
|
||||
Example:
|
||||
- The order state machine in src/orders/state.ts is complex — always read it fully before modifying
|
||||
- Payment webhooks are idempotent — every handler must check for duplicate event IDs
|
||||
-->
|
||||
|
||||
- [KNOWN PROBLEM AREA 1]
|
||||
- [KNOWN PROBLEM AREA 2]
|
||||
Loading…
Add table
Add a link
Reference in a new issue