From 2f27f50ef389f9dd635dd44ed92b16e246b85042 Mon Sep 17 00:00:00 2001 From: Nano Taboada Date: Mon, 27 Jul 2026 10:04:40 -0300 Subject: [PATCH] docs(claude): migrate workflows out of CLAUDE.md to skills Move "Pre-commit Checks" (now a pointer to the existing /pre-commit skill), "Creating Issues", and "Key workflows" out of the always-loaded CLAUDE.md into two new on-demand skills (create-issue, key-workflows), cutting ~2.2k always-resident characters per session. Found and applied by the new /doctor command. Co-authored-by: Claude Sonnet 5 --- .claude/skills/create-issue/SKILL.md | 21 ++++++++++++++++ .claude/skills/key-workflows/SKILL.md | 16 ++++++++++++ CHANGELOG.md | 6 +++++ CLAUDE.md | 36 +++------------------------ 4 files changed, 46 insertions(+), 33 deletions(-) create mode 100644 .claude/skills/create-issue/SKILL.md create mode 100644 .claude/skills/key-workflows/SKILL.md diff --git a/.claude/skills/create-issue/SKILL.md b/.claude/skills/create-issue/SKILL.md new file mode 100644 index 0000000..88a11b0 --- /dev/null +++ b/.claude/skills/create-issue/SKILL.md @@ -0,0 +1,21 @@ +--- +name: create-issue +description: Draft a GitHub Issue as the spec artifact for Spec-Driven Development (SDD) before implementing a feature or bug fix in this project. +--- + +This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code. + +**Feature request** (`enhancement` label): +- **Problem**: the pain point being solved +- **Proposed Solution**: expected behavior and functionality +- **Suggested Approach** *(optional)*: implementation plan if known +- **Acceptance Criteria**: at minimum — behaves as proposed, tests added/updated, no regressions +- **References**: related issues, docs, or examples + +**Bug report** (`bug` label): +- **Description**: clear summary of the bug +- **Steps to Reproduce**: numbered, minimal steps +- **Expected / Actual Behavior**: one section each +- **Environment**: runtime versions + OS +- **Additional Context**: logs, screenshots, stack traces +- **Possible Solution** *(optional)*: suggested fix or workaround diff --git a/.claude/skills/key-workflows/SKILL.md b/.claude/skills/key-workflows/SKILL.md new file mode 100644 index 0000000..239f952 --- /dev/null +++ b/.claude/skills/key-workflows/SKILL.md @@ -0,0 +1,16 @@ +--- +name: key-workflows +description: Step-by-step guides for adding an endpoint or modifying the schema in this Spring Boot project, plus the branch/commit proposal to make after finishing work. +--- + +**Add an endpoint**: Define DTO in `models/` with Bean Validation → add service method in `services/` with `@Transactional` → create controller endpoint with `@Operation` annotation → add tests → run `./mvnw clean test jacoco:report`. + +**Modify schema**: Create a new Flyway migration `src/main/resources/db/migration/V{N}__description.sql` (production path) → update `@Entity` in `models/Player.java` → update DTOs if API changes → also update `src/test/resources/ddl.sql` and `dml.sql` (tests use Spring SQL init, not Flyway) → update service, repository, and tests → run `./mvnw clean test`. Do not manually edit the SQLite file in `storage/`; Flyway owns it. + +**After completing work**: Suggest a branch name (e.g. `feat/113-add-player-stats`) and a commit message following Conventional Commits including co-author line: + +```text +feat(scope): description (#issue) + +Co-authored-by: Claude Sonnet 5 +``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 010733c..b5d1841 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,12 @@ Release names follow the **historic football clubs** naming convention (A–Z): `/pre-commit`; move CodeRabbit review to run against the uncommitted CHANGELOG diff; separate commit-message approval from the actual commit so checks run in between +- Trim `CLAUDE.md`: replace the "Pre-commit Checks" list with a pointer to the + existing `/pre-commit` skill, and move "Creating Issues" and "Key workflows" + into two new on-demand skills (`create-issue`, `key-workflows`) so their + content only loads when needed instead of every session — found and applied + by the new `/doctor` command, per + [the new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models) ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index 8520527..01fea08 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,12 +68,7 @@ docker compose down -v ### Pre-commit Checks -1. `./mvnw clean install` — must succeed -2. All tests pass -3. Check coverage at `target/site/jacoco/index.html` -4. No compilation warnings -5. Commit message follows Conventional Commits format (enforced by commitlint) -6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `docs/adr/`. +Run `/pre-commit` to execute the full pre-commit checklist for this project before proposing a commit. ### Commits @@ -114,36 +109,11 @@ Example: `feat(api): add player stats endpoint (#42)` ### Creating Issues -This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code. - -**Feature request** (`enhancement` label): -- **Problem**: the pain point being solved -- **Proposed Solution**: expected behavior and functionality -- **Suggested Approach** *(optional)*: implementation plan if known -- **Acceptance Criteria**: at minimum — behaves as proposed, tests added/updated, no regressions -- **References**: related issues, docs, or examples - -**Bug report** (`bug` label): -- **Description**: clear summary of the bug -- **Steps to Reproduce**: numbered, minimal steps -- **Expected / Actual Behavior**: one section each -- **Environment**: runtime versions + OS -- **Additional Context**: logs, screenshots, stack traces -- **Possible Solution** *(optional)*: suggested fix or workaround +This project uses Spec-Driven Development (SDD): discuss in Plan mode first, create a GitHub Issue as the spec artifact, then implement. Always offer to draft an issue before writing code. See the `create-issue` skill for the feature/bug issue templates. ### Key workflows -**Add an endpoint**: Define DTO in `models/` with Bean Validation → add service method in `services/` with `@Transactional` → create controller endpoint with `@Operation` annotation → add tests → run `./mvnw clean test jacoco:report`. - -**Modify schema**: Create a new Flyway migration `src/main/resources/db/migration/V{N}__description.sql` (production path) → update `@Entity` in `models/Player.java` → update DTOs if API changes → also update `src/test/resources/ddl.sql` and `dml.sql` (tests use Spring SQL init, not Flyway) → update service, repository, and tests → run `./mvnw clean test`. Do not manually edit the SQLite file in `storage/`; Flyway owns it. - -**After completing work**: Suggest a branch name (e.g. `feat/add-player-stats`) and a commit message following Conventional Commits including co-author line: - -```text -feat(scope): description (#issue) - -Co-authored-by: Claude Sonnet 4.6 -``` +See the `key-workflows` skill for the step-by-step guides to adding an endpoint, modifying the schema, and what to propose after finishing work. ## Invariants (never change without explicit discussion)