agentleFS
TarasTsavolykTarasTsavolyk/claude-code-frontend/CLAUDE.md

claude-code-frontend

CLAUDE.md1 starsChanged 4 months agoMITView on GitHub

This file is always-loaded memory, so it holds only what the repo can't tell you itself. The stack, the scripts, the folder layout, TypeScript-or-not — all of that is in package.json, tsconfig.json, and the source tree: read them rather than trusting a copy here, because a copy drifts and nothing warns you. What's left below is the part that isn't written down anywhere else. Domain conventions live in .claude/rules/ (path-scoped, plus the global workflow.md). Workflows live in .claude/skills/. How the…

  • Reads credentials
  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    No lockfile? Ask which to use.

    line 22
  2. Distinctive:

    Understand, plan, then wait for a go-ahead: Read the real code first — read-only investigation needs no approval and is what keeps a plan …

    line 64
  3. Distinctive:

    Remove only what YOUR change orphaned — flag pre-existing dead code, don't delete it.

    line 74
  4. Very specific:

    Never commit directly to main/master — branch first (feature/…, fix/…, chore/…).

    line 83
  5. Distinctive:

    Run the quality gate before every commit.

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

<PROJECT_NAME>

This file is always-loaded memory, so it holds only what the repo can't tell you itself. The stack, the scripts, the folder layout, TypeScript-or-not — all of that is in package.json, tsconfig.json, and the source tree: read them rather than trusting a copy here, because a copy drifts and nothing warns you. What's left below is the part that isn't written down anywhere else.

Domain conventions live in .claude/rules/ (path-scoped, plus the global workflow.md). Workflows live in .claude/skills/. How the lead, skills, and agents combine is defined in .claude/rules/workflow.md. The kit is Vue-3-only: rules, skills, and agents are written directly against Vue 3 APIs. /wizard adapts this file to the host project.

Package manager

Detect from the lockfile and use that one consistently — never mix:

  • package-lock.json → npm
  • pnpm-lock.yaml → pnpm
  • yarn.lock → yarn
  • bun.lock / bun.lockb → bun

No lockfile? Ask which to use. <pm> is the detected manager: <pm> install, <pm> run <script> (the explicit run form works for npm/pnpm/yarn/bun), <pm> exec <bin> (or npx <bin>).

Script names come from package.json — read it, don't assume. Only the <pm> prefix is fixed; the names vary by project (typecheck or type-check, test or test:unit), and a copy of them in this file would go stale the first time someone adds a script.

Quality gate (must pass before any commit)

lint → typecheck (TypeScript only) → test, in that order — cheapest failure first. New behavior requires tests. No exceptions. A PreToolUse hook (.claude/hooks/pre-commit-gate.mjs) blocks git commit until it passes, resolving the script names itself and printing the gate it ran; the README covers gating terminal commits too.

The rules

Each file in .claude/rules/ is the single home for its domain, and loads by itself when you touch a file it matches. This list is for the case where that hasn't happened: you're about to create a file, so nothing has been read to trigger it. Go read the rule — these lines don't stand in for one.

RuleOwnsRead it when
architecture.mdlayout, decomposition, component API, logic placement, routingbefore adding a component, composable, store, or route
code-style.mdTS/JS conventions, SFC form, naming, importsalways — any JS/TS file
styling.mddesign tokens, responsive & dark mode, your approachbefore any markup or CSS
testing.mdwhat to test, harness wiring, the barbefore a test — and new behavior needs one
accessibility.mdWCAG 2.2 AA — semantics, keyboard, focus, contrastany interactive markup · a requirement
security.mdtrust boundary, XSS sinks, secrets, tokens, CSPuntrusted data, auth, storage, raw HTML · a requirement
data-fetching.mdvalidation, the four async statesany network call
error-handling.mdexpected vs unexpected, boundaries, observabilityany failure path
performance.mdloading, rendering, assets, budgets, browser floorlists, bundles, new deps, assets
config.mdone validated module, Vite vs Nuxt env, build-time vs runtimereading env or adding a config value
forms.mdvalidation, submission state, accessible fieldsany form
i18n.mdkeys, pluralization, formatting, RTLthe project is internationalized — else skip
ssr.mdserver/client seam, hydrationthe project server-renders — else skip

Scope lives in each rule's paths: frontmatter, not here — a second copy would drift. workflow.md is absent above because it is the one global rule: always loaded, never waiting to be found.

The server is the only trust boundary — every client-side control, security.md included, is defense-in-depth.

Working principles

  • Understand, plan, then wait for a go-ahead. Read the real code first — read-only investigation needs no approval and is what keeps a plan from being a guess. Then present it: what you'll touch, the approach, your assumptions, the edge cases, how it will be verified. If the request has several reasonable readings, or a simpler approach would meet the goal, put that in the plan instead of silently choosing — pushing back is part of planning, not a detour from it. Then stop until the user approves: no edits, no new files, no state-changing commands. "It's a one-liner" is not an exemption; that is exactly when a wrong assumption ships unnoticed. If the plan proves wrong mid-way, stop and re-present it rather than improvising past it.
  • Simplicity first: write the minimum code that solves the stated problem — no speculative features, abstractions, configurability, or error handling for cases that can't occur; no abstraction for single-use code.
  • Surgical changes: touch only what the task requires; match the existing style; don't refactor what isn't broken. Remove only what YOUR change orphaned — flag pre-existing dead code, don't delete it.
  • Goal-driven: turn the task into a verifiable goal and loop until verified — run the quality gate, never stop at "should work". A bug's regression test fails before the fix; refactors stay green throughout (see rules/testing.md).

The first principle is enforced, not just written: settings.json sets defaultMode: "plan", so edits are refused until a plan is accepted. Approval before committing is a separate, later stop — see Git.

Git

  • Never commit directly to main/master — branch first (feature/…, fix/…, chore/…). Never force-push or rewrite shared history without explicit human confirmation. Never commit secrets/.env/keys — if one is staged, stop and flag it.
  • Conventional Commits: type(scope): summary (feat fix refactor perf test docs chore build ci style), imperative, ≤72-char subject; the body explains why. Small, focused commits over one giant commit.
  • Run the quality gate before every commit. Keep PRs small and single-purpose; the description covers What, Why, How to test, screenshots for UI changes, and any a11y/perf impact.
  • Approval before committing or opening a PR: show the changed files (git status --short / git diff --stat) and the full commit message or PR description verbatim, then wait — let the user edit or append first. settings.json puts git commit/git push behind ask; this defines what to surface at that stop. Never push on the user's behalf without confirmation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.