Skip to content

CLAUDE.md

Latest commit

 

History

History
101 lines (82 loc) · 4.99 KB

CLAUDE.md

File metadata and controls

101 lines (82 loc) · 4.99 KB
Raw

anartia is a JavaScript-optional public web frontend for Bluesky, built with SvelteKit and Vite, deployed to Cloudflare Workers.

development notes

project management

  • Node.js and pnpm is managed by mise
  • install dependencies with pnpm install
  • run dev server with pnpm dev
  • build with pnpm build
  • preview production build with pnpm preview
  • format via pnpm format (Prettier)
  • lint via pnpm lint (Prettier check)
  • typecheck via pnpm check (svelte-check)
  • check pnpm view <package> before adding a new dependency

code writing

  • new files should be in kebab-case
  • use tabs for indentation, spaces allowed for diagrams in comments
  • use single quotes for strings; use template literals for localization strings (user-facing strings, error messages)
  • add trailing commas
  • prefer arrow functions, but use regular methods in classes unless arrow functions are necessary (e.g., when passing the method as a callback that needs this binding)
  • use braces for control statements, even single-line bodies
  • use bare blocks { } to group related code and limit variable scope
  • avoid barrel exports (index files that re-export from other modules); import directly from source
  • use // #region <name> and // #endregion to denote regions when a file needs to contain a lot of code
  • a parameter should be optional only when callers genuinely split between passing a value and relying on the default; if every caller passes a value, make it required; if no caller would ever change it, it should not be a parameter at all
  • avoid optional parameters that change behavioral modes or make the function do different things based on presence/absence; prefer a separate function with a clearer name instead
  • avoid type assertions (as Type, as const) unless TypeScript actually errors without them; when it does error, prefer finding a solution that satisfies the type system naturally before resorting to an assertion

documentation

  • documentations include README, code comments, commit messages
  • any writing should be in lowercase, except for proper nouns, acronyms and 'I'; this does not apply to public-facing interfaces like web UI
  • only comment non-trivial code, focusing on why rather than what
  • write comments and JSDoc in lowercase (except proper nouns, acronyms, and 'I')
  • add JSDoc comments to new publicly exported functions, methods, classes, fields, and enums
  • JSDoc should include proper annotations:
    • use @param for parameters (no dashes after param names)
    • use @returns for return values
    • use @throws for exceptions when applicable
    • keep descriptions concise but informative

agentic coding

  • .research/ directory in the project root serves as a workspace for temporary experiments, analysis, and planning materials. create if not present (it's gitignored). this directory may contain cloned repositories or other reference materials that can help inform implementation decisions
  • this document is intentionally incomplete; discover everything else in the repo
  • don't make assumptions or speculate about code, plans, or requirements without exploring first; pause and ask for clarification when you're still unsure after looking into it
  • in plan mode, present the plan for review before exiting to allow for feedback or follow-up questions
  • when debugging problems, isolate the root cause first before attempting fixes: add logging, reproduce the issue, narrow down the scope, and confirm the exact source of the problem

Claude Code-specific

  • Explore subagent may not be accurate; verify findings as needed
  • never spawn subagents to read and return file contents; read files directly in the main context. subagents should perform searches or answer specific questions, not act as file I/O proxies

external repository research

use @oomfware/cgr to ask questions about external repositories:

npx @oomfware/cgr ask [options] <repo>[#branch] <question>

options:
  -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
  -d, --deep            clone full history (enables git log/blame/show)
  -w, --with <repo>     additional repository to include, supports #branch (repeatable)

useful repositories for development:

  • github.com/bluesky-social/atproto for AT Protocol reference implementation, lexicons, XRPC
  • github.com/bluesky-social/social-app for Bluesky app patterns, API usage examples
  • github.com/bluesky-social/proposals for AT Protocol proposals and specifications
  • github.com/bluesky-social/atproto-website for AT Protocol spec documentation
  • github.com/mary-ext/atcute for the AT Protocol client library used in this project
  • github.com/sveltejs/kit for SvelteKit framework internals and patterns
  • github.com/sveltejs/svelte for Svelte 5 runes, components, and runtime

broad questions work for getting oriented; detailed questions get precise answers. include file/folder paths when you know them, and reference details from previous answers in follow-ups.

run npx @oomfware/cgr --help for more options.