From 6070f55358062d5c177b6fe7f3495749ddf0e665 Mon Sep 17 00:00:00 2001 From: Kato Hiroki Date: Fri, 20 Mar 2026 05:27:40 +0000 Subject: [PATCH 1/2] docs: Consolidate coding rules and strengthen test policy - coding-style.md: Add No Hard-Coded Values, Function Ordering, and Svelte 5 docs sections - coding-style.md: Absorb content from svelte-docs.md (now redundant) - svelte-docs.md: Delete (merged into coding-style.md) - testing.md: Add 'Tests Ship with the Implementation' section Co-Authored-By: Claude Sonnet 4.6 --- .claude/rules/coding-style.md | 41 +++++++++++++++++++++++++++++++++++ .claude/rules/svelte-docs.md | 18 --------------- .claude/rules/testing.md | 6 +++++ 3 files changed, 47 insertions(+), 18 deletions(-) delete mode 100644 .claude/rules/svelte-docs.md diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md index 8b82be77e..8fa80ac1f 100644 --- a/.claude/rules/coding-style.md +++ b/.claude/rules/coding-style.md @@ -66,6 +66,47 @@ console.log('Workbook created successfully'); Prefer placing the single authoritative log in the service layer; remove duplicate logs in route handlers that cover the same event. +## No Hard-Coded Values + +Extract magic numbers and strings to named constants. Never embed literal values whose meaning is not self-evident from the type or immediate context. + +```typescript +// Bad +if (grade >= 11) { ... } + +const url = '/api/workbooks/submit'; + +// Good +const MIN_GRADE = 11; + +if (grade >= MIN_GRADE) { ... } + +const SUBMIT_URL = '/api/workbooks/submit'; +``` + +Place constants at the top of the file, or in a dedicated `constants/` module when shared across files. + +## Function Ordering + +Within a file, order declarations as follows: + +1. Exported functions and classes (public API first) +2. Internal helper functions (supporting the exports above) + +Group functions by concern — helpers should appear immediately after the exported function they support, not at the end of the file. This makes the call graph readable top-to-bottom. + +## Svelte 5: Prefer Official Docs Over Training Knowledge + +When Svelte 5 behavior is unclear, fetch the official docs directly via WebFetch instead of relying on training knowledge. + +URL pattern: `https://svelte.dev/docs/svelte/{section}` + +Examples: + +- `$effect` behavior → `https://svelte.dev/docs/svelte/$effect` +- Stores usage → `https://svelte.dev/docs/svelte/stores` +- Runes overview → `https://svelte.dev/docs/svelte/what-are-runes` + ## Async Rollback: Capture State Before `await` Capture `$state` values before the first `await` for safe rollback. A concurrent update can overwrite the variable while awaiting: diff --git a/.claude/rules/svelte-docs.md b/.claude/rules/svelte-docs.md deleted file mode 100644 index 01aca4d30..000000000 --- a/.claude/rules/svelte-docs.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: Svelte official documentation reference -paths: - - 'src/**/*.svelte' - - 'src/**/*.ts' ---- - -# Svelte Official Documentation - -When Svelte 5 behavior is unclear, fetch the official docs directly via WebFetch instead of relying on training knowledge. - -URL pattern: `https://svelte.dev/docs/svelte/{section}` - -Examples: - -- `$effect` behavior → `https://svelte.dev/docs/svelte/$effect` -- Stores usage → `https://svelte.dev/docs/svelte/stores` -- Runes overview → `https://svelte.dev/docs/svelte/what-are-runes` diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md index 85f4b5d72..1129a0a47 100644 --- a/.claude/rules/testing.md +++ b/.claude/rules/testing.md @@ -13,6 +13,12 @@ paths: Write all test titles in English. Use descriptive sentences that state the expected behavior (e.g., `'returns empty array when workbooks is empty'`). Japanese is only acceptable in inline comments or fixture strings that represent real user-facing content. +## Tests Ship with the Implementation + +Tests must be included in the same commit as the implementation they cover. "Add tests later" is not acceptable — a feature or fix is not done until its tests pass. + +If a task description does not mention tests, add them anyway for any non-trivial logic. + ## Test Integrity - Never delete, comment out, or weaken assertions (e.g. `toEqual` → `toBeDefined`) to make tests pass From 7b8e05e534ed4b0c31821cfedefb1cf51e6add7e Mon Sep 17 00:00:00 2001 From: Kato Hiroki Date: Fri, 20 Mar 2026 05:45:36 +0000 Subject: [PATCH 2/2] docs: Clarify shared helper placement in Function Ordering rule Co-Authored-By: Claude Sonnet 4.6 --- .claude/rules/coding-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md index 8fa80ac1f..f21ac499c 100644 --- a/.claude/rules/coding-style.md +++ b/.claude/rules/coding-style.md @@ -93,7 +93,7 @@ Within a file, order declarations as follows: 1. Exported functions and classes (public API first) 2. Internal helper functions (supporting the exports above) -Group functions by concern — helpers should appear immediately after the exported function they support, not at the end of the file. This makes the call graph readable top-to-bottom. +Shared helper functions (used by two or more exports) should be grouped at the end of the file. ## Svelte 5: Prefer Official Docs Over Training Knowledge