Plan: CLAUDE.md and Skills for recurring workflows - #443
Merged
Conversation
Audits what the repo already documents well (README, docs/handlers.md, docs/forms.md, the per-folder eslint import bans) against what is written down nowhere — the codegen prerequisite that makes apps/api uncompilable on a fresh clone, the four stale root-level plans describing the removed controllers layer, the Makefile's wrong MIGRATIONS_DIR default, and the barrel/test/story siblings every slice is expected to carry. Proposes a root CLAUDE.md plus one per area (libs/ui, apps/api) so frontend rules are not paid for by Go-only sessions, and six Skills for the workflows the file counts show are templated: verify, ui-feature-slice, api-endpoint, db-migration, write-spec, docs-site-page, e2e-spec. Phases are sized one per PR. No application code is touched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VM4BAxzahdoj9mzpEGRaYQ
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
mnindrazaka
added a commit
that referenced
this pull request
Sep 12, 2026
* docs: plan a CLAUDE.md and Skills for the repo's recurring workflows (#443) Audits what the repo already documents well (README, docs/handlers.md, docs/forms.md, the per-folder eslint import bans) against what is written down nowhere — the codegen prerequisite that makes apps/api uncompilable on a fresh clone, the four stale root-level plans describing the removed controllers layer, the Makefile's wrong MIGRATIONS_DIR default, and the barrel/test/story siblings every slice is expected to carry. Proposes a root CLAUDE.md plus one per area (libs/ui, apps/api) so frontend rules are not paid for by Go-only sessions, and six Skills for the workflows the file counts show are templated: verify, ui-feature-slice, api-endpoint, db-migration, write-spec, docs-site-page, e2e-spec. Phases are sized one per PR. No application code is touched. Claude-Session: https://claude.ai/code/session_01VM4BAxzahdoj9mzpEGRaYQ Co-authored-by: Claude <noreply@anthropic.com> * docs: rewrite root CLAUDE.md as a rule sheet and index (#444) Implements Phase 1 of docs/plan-claude-md-and-skills.md: keeps the existing comment rule verbatim and first, then adds the traps an agent otherwise rediscovers by trial and error (the gitignored Go codegen prerequisite, the four stale root-level planning docs), a summary of the ESLint-enforced layer boundaries with the eslintrc as authority, the conventions lint can't catch (usecase FSMs, barrel exports, *domain.Error, mockgen, migration gotchas), and a doc index. No prose duplicated from README.md; every link resolves. Claude-Session: https://claude.ai/code/session_012qMpjsE9bwgZvWngdWkNhs Co-authored-by: Claude <noreply@anthropic.com> * docs: add libs/ui CLAUDE.md for frontend slice rules (#445) Phase 2 of docs/plan-claude-md-and-skills.md: the FSM use case shape, handler/form/screen boundaries with their authoritative docs, barrel discipline, and the test-harness gotchas that lint cannot catch. Claude-Session: https://claude.ai/code/session_011QausgGEHDtqAXUR1p2XGf Co-authored-by: Claude <noreply@anthropic.com> * docs: add apps/api/CLAUDE.md for backend slice rules (phase 3) (#446) Adds the backend area rules file from docs/plan-claude-md-and-skills.md phase 3: the domain/data/presentation file shape per feature, the *domain.Error contract, public-vs-authenticated routing, and the migrations/MIGRATIONS_DIR trap, each cited to its authority in the repo. Claude-Session: https://claude.ai/code/session_011y6QEDeaJ4m2XyhcjYsHUu Co-authored-by: Claude <noreply@anthropic.com> * docs: add verify skill for choosing the narrow test/lint command (phase 4) (#447) Adds the verify skill from docs/plan-claude-md-and-skills.md phase 4: a what-changed to command table, the api-contract codegen prerequisite, single-file test loops, and what pr-test.yml/e2e-main.yml will and will not catch before merge. Claude-Session: https://claude.ai/code/session_01H1vxxZZ2mXWVEgsGqzGXyM Co-authored-by: Claude <noreply@anthropic.com> * docs: add ui-feature-slice skill for frontend slice template (phase 5) (#448) Documents the file set, FSM use-case skeleton, handler/form/screen rules, composition root shape, and test pattern for adding a frontend feature slice in libs/ui, using the Budget slice as the verified reference example. Claude-Session: https://claude.ai/code/session_01Jbag8Fr19FqhGcH3DnP1tA Co-authored-by: Claude <noreply@anthropic.com> * docs: add api-endpoint skill for Go REST feature template (phase 6) (#449) Claude-Session: https://claude.ai/code/session_01MrPsaMenWC7KCKqjyVqJ3g Co-authored-by: Claude <noreply@anthropic.com> * docs: add db-migration skill for golang-migrate workflows (#450) Phase 7 of docs/plan-claude-md-and-skills.md: a Skill for creating, writing, and running apps/api MySQL migrations, covering the MIGRATIONS_DIR default mismatch and the go.work install trap. Claude-Session: https://claude.ai/code/session_019PubCtkZbjkU1fSShMVCKn Co-authored-by: Claude <noreply@anthropic.com> * docs: add write-spec skill for PRD/TRD/plan authoring (#451) Phase 8 of docs/plan-claude-md-and-skills.md: documents the docs/ house style (PRD vs TRD vs plan, D-numbered decisions, one-phase-per-PR sizing) so specs stay consistent and their decision numbers stay stable. Claude-Session: https://claude.ai/code/session_01Pjw1aXnLk2WBXqtEEDLGQj Co-authored-by: Claude <noreply@anthropic.com> * docs: add docs-site-page skill for VitePress feature pages (phase 9) (#452) Phase 9 of docs/plan-claude-md-and-skills.md: documents where a feature page and its screenshots/diagrams belong, and the sidebar-wiring step in .vitepress/config.ts that has no error when skipped, leaving a page built but unreachable. Claude-Session: https://claude.ai/code/session_01Asbozcv2zvRwh5csDDNgcp Co-authored-by: Claude <noreply@anthropic.com> * skill: add e2e-spec for Playwright e2e coverage in pos-web-e2e/order-web-e2e (#453) Phase 10 of docs/plan-claude-md-and-skills.md (S7). Documents where specs live, the seeded environment and pre-baked auth CI assumes, the testMatch/testIgnore routing for no-auth and mobile projects, the DOKU stub flow, and why the suite must be run green locally since pr-test.yml never runs it. Claude-Session: https://claude.ai/code/session_01AMGf2tLqmznUEDx5HM48Xa Co-authored-by: Claude <noreply@anthropic.com> * chore: add session-start hook and command allowlist (phase 11) (#454) Runs the api-contract codegen targets on SessionStart so apps/api resolves from the first turn instead of showing phantom Go errors on a cold clone, and allowlists the read-only test/lint/codegen commands the new skills rely on. Claude-Session: https://claude.ai/code/session_01MXUeuX9Aq7KFdzCUvfxaqK Co-authored-by: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This document specifies the structure and content of a new
CLAUDE.mdsystem and six reusable Skills to guide AI agents through the repo's conventions and templated workflows.Summary
The repo has strict, non-obvious conventions (FSM-based use cases, inverted
useFormownership, gitignored generated Go code, stale planning documents) that agents must rediscover every session. Separately, day-to-day work is highly templated: 87 use cases, 58 handler/screen pairs, 25 migrations, all following a single pattern. This plan introduces:CLAUDE.mdfiles (root + frontend + backend areas) that index rules and link to their authorities rather than duplicating prose.claude/skills/<name>/SKILL.md) for the most-repeated, highest-failure-cost workflows:verify,ui-feature-slice,api-endpoint,db-migration,write-spec,docs-site-page,e2e-specEach skill includes the template file structure, the specific gotchas that cannot be inferred from siblings, and the exact verification command.
Key sections
CLAUDE.mdis a rule sheet and index, not a second README; Skills carry traps, not just templates; every skill names its verification commande2e-specnot listed in the count)Acceptance criteria
https://claude.ai/code/session_01VM4BAxzahdoj9mzpEGRaYQ