Skip to content

Move path-specific guidance into .claude/rules - #44

Merged
solcott merged 1 commit into
mainfrom
docs/path-scoped-rules
Sep 30, 2026
Merged

solcott merged 1 commit into
mainfrom
docs/path-scoped-rules

Conversation

@solcott

@solcott solcott commented Sep 30, 2026

Copy link
Copy Markdown
Owner

Summary

Most of what breaks in this repo fails silently. The guidance for it was kept in skills, and AGENTS.md asked the agent to "read the matching skill before editing". That only worked when the model remembered to. This PR moves those per-directory invariants into path-scoped rules (.claude/rules/*.md with paths: frontmatter). Claude Code loads a rule automatically whenever a matching file is read.

  • 11 new rules: swift-export, network, web, desktop, app-icons, compose-ui, compose-resources, screens, metro-graph, build-scripts, kmp-tests. .gitignore now un-ignores .claude/rules/.
  • Skills:
    • network-apollo, web-app, apple-app-icons and compose-previews are deleted; their content is now in rules in full.
    • desktop-app is trimmed to hot reload and the MCP server, dependency-bump to its verification procedure, and add-screen points to the rules instead of repeating them.
    • apple-app, verify, pr-review and compose-fonts stay as task skills.
  • AGENTS.md (26.5k → ~20k chars, always loaded):
    • It now routes to rules by path and to skills by task.
    • Content a session can derive from the code is dropped: migration history, package naming, SDK levels, and the daemon JVM block.
    • Platform commands and build-script detail moved into their rules.
  • Stale facts corrected:
    • detekt runs on every module via the conventions, with ModifierMissing/ModifierNotUsedAtRoot active and run by CI's ./gradlew build. AGENTS.md and the compose-conventions agent still said it covered only build-logic.
    • The live config is config/detekt/detekt.yml. detekt/detekt.yml looks like a leftover and is left in place.
    • "Thirteen modules" is now eleven.
    • The Testing row is now kotlin.test + Turbine.
  • renovate.json5 comments point at the network rule instead of the deleted skill. The rule also gains the sql.js "declared twice, must match" invariant, which only Renovate's config recorded before.

Test plan

  • Documentation only; no source changes, so verify requires no build.
  • No references to the deleted skills remain (git grep).
  • Every item in verify's "fails at runtime with a clean build" list is covered by a rule.
  • In a fresh session, open a file under one rule's paths: and confirm the rule loads, then open an unrelated file and confirm it does not.

🤖 Generated with Claude Code

Invariants that fail silently and belong to one directory now live in
path-scoped rules that Claude Code loads when a matching file is read,
instead of skills that loaded only if the model remembered to open them.

- Add 11 rules under .claude/rules/, and un-ignore the directory.
- Delete the network-apollo, web-app, apple-app-icons and
  compose-previews skills, whose content moved into rules in full.
- Trim desktop-app to hot reload, dependency-bump to its verification
  procedure, and add-screen to pointers.
- AGENTS.md: route to rules and task skills, drop derivable content,
  move platform commands into their rules.
- Correct stale facts: detekt now runs on every module (config is
  config/detekt/detekt.yml), there are eleven modules, and KMP tests
  use kotlin.test rather than JUnit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@solcott
solcott merged commit d7adc32 into main Sep 30, 2026
1 check passed
@solcott
solcott deleted the docs/path-scoped-rules branch September 30, 2026 18:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant