Skip to content

CLAUDE.md

Latest commit

 

History

History
155 lines (112 loc) · 6.77 KB

CLAUDE.md

File metadata and controls

155 lines (112 loc) · 6.77 KB

Dual-Graph Context Policy

This project uses a local dual-graph MCP server for efficient context retrieval.

MANDATORY: Always follow this order

  1. Call graph_continue first — before any file exploration, grep, or code reading.

  2. If graph_continue returns needs_project=true: call graph_scan with the current project directory (pwd). Do NOT ask the user.

  3. If graph_continue returns skip=true: project has fewer than 5 files. Do NOT do broad or recursive exploration. Read only specific files if their names are mentioned, or ask the user what to work on.

  4. Read recommended_files using graph_read — one call per file.

    • graph_read accepts a single file parameter (string). Call it separately for each recommended file. Do NOT pass an array or batch multiple files into one call.
    • recommended_files may contain file::symbol entries (e.g. src/auth.ts::handleLogin). Pass them verbatim to graph_read(file: "src/auth.ts::handleLogin") — it reads only that symbol's lines, not the full file.
    • Example: if recommended_files is ["src/auth.ts::handleLogin", "src/db.ts"], call graph_read(file: "src/auth.ts::handleLogin") and graph_read(file: "src/db.ts") as two separate calls (they can be parallel).

  5. Check confidence and obey the caps strictly:

    • confidence=high -> Stop. Do NOT grep or explore further.
    • confidence=medium -> If recommended files are insufficient, call fallback_rg at most max_supplementary_greps time(s) with specific terms, then graph_read at most max_supplementary_files additional file(s). Then stop.
    • confidence=low -> Call fallback_rg at most max_supplementary_greps time(s), then graph_read at most max_supplementary_files file(s). Then stop.

Token Usage

A token-counter MCP is available for tracking live token usage.

  • To check how many tokens a large file or text will cost before reading it: count_tokens({text: "<content>"})
  • To log actual usage after a task completes (if the user asks): log_usage({input_tokens: <est>, output_tokens: <est>, description: "<task>"})
  • To show the user their running session cost: get_session_stats()

Live dashboard URL is printed at startup next to "Token usage".

Rules

  • Do NOT use rg, grep, or bash file exploration before calling graph_continue.
  • Do NOT do broad/recursive exploration at any confidence level.
  • max_supplementary_greps and max_supplementary_files are hard caps - never exceed them.
  • Do NOT dump full chat history.
  • Do NOT call graph_retrieve more than once per turn.
  • After edits, call graph_register_edit with the changed files. Use file::symbol notation (e.g. src/auth.ts::handleLogin) when the edit targets a specific function, class, or hook.

Context Store

Whenever you make a decision, identify a task, note a next step, fact, or blocker during a conversation, append it to .dual-graph/context-store.json.

Entry format:

{"type": "decision|task|next|fact|blocker", "content": "one sentence max 15 words", "tags": ["topic"], "files": ["relevant/file.ts"], "date": "YYYY-MM-DD"}

To append: Read the file → add the new entry to the array → Write it back → call graph_register_edit on .dual-graph/context-store.json.

Rules:

  • Only log things worth remembering across sessions (not every minor detail)
  • content must be under 15 words
  • files lists the files this decision/task relates to (can be empty)
  • Log immediately when the item arises — not at session end

Session End

When the user signals they are done (e.g. "bye", "done", "wrap up", "end session"), proactively update CONTEXT.md in the project root with:

  • Current Task: one sentence on what was being worked on
  • Key Decisions: bullet list, max 3 items
  • Next Steps: bullet list, max 3 items

Keep CONTEXT.md under 20 lines total. Do NOT summarize the full conversation — only what's needed to resume next session.

Project: Resgrid Unit (React Native / Expo)

Tech Stack

TypeScript · React Native · Expo (managed, prebuild) · Zustand · React Query · React Hook Form · react-i18next · react-native-mmkv · Axios · @rnmapbox/maps · gluestack-ui · lucide-react-native

Code Style

  • Write concise, type-safe TypeScript. Avoid any; use precise types and interfaces for props/state.
  • Use functional components and hooks; never class components. Use React.FC for typed components.
  • Enable strict mode in tsconfig.json.
  • Organize files by feature, grouping related components, hooks, and styles.
  • All components must be mobile-friendly and responsive, supporting both iOS and Android.
  • This is an Expo managed project using prebuild — do not make native code changes outside Expo prebuild capabilities.

Naming Conventions

  • Variables and functions: camelCase (e.g., isFetchingData, handleUserInput)
  • Components: PascalCase (e.g., UserProfile, ChatScreen)
  • Files and directories: lowercase-hyphenated (e.g., user-profile.tsx, chat-screen/)

Styling

  • Use gluestack-ui components from components/ui when available.
  • For anything without a Gluestack component, use StyleSheet.create() or Styled Components.
  • Support both dark mode and light mode.
  • Follow WCAG accessibility guidelines for mobile.

Performance

  • Minimize useEffect, useState, and heavy computation inside render methods.
  • Use React.memo() for components with static props.
  • Optimize FlatList with removeClippedSubviews, maxToRenderPerBatch, windowSize, and getItemLayout when items have a consistent size.
  • Avoid anonymous functions in renderItem or event handlers.

Internationalization

  • All user-visible text must be wrapped in t() from react-i18next.
  • Translation dictionary files live in src/translations/.

Libraries — use these, not alternatives

Purpose Library
Package manager yarn
State management zustand
Data fetching react-query
Forms react-hook-form
i18n react-i18next
Local storage react-native-mmkv
Secure storage Expo SecureStore
HTTP axios
Maps / navigation @rnmapbox/maps
Icons lucide-react-native (use directly in markup, not via gluestack Icon wrapper)

Conditional Rendering

Use ternary ? : for conditional rendering — never &&.

Testing

  • Use Jest. Generate tests for all new components, services, and logic.
  • Ensure tests run without errors before considering a task done.

Best Practices

  • Follow React Native's threading model for smooth UI performance.
  • Use React Navigation for navigation and deep linking.
  • Handle errors gracefully and provide user feedback.
  • Implement proper offline support.
  • Optimize for low-end devices.