Skip to content

CLAUDE.md

Latest commit

 

History

History
89 lines (63 loc) · 4.02 KB

CLAUDE.md

File metadata and controls

89 lines (63 loc) · 4.02 KB

flash-list

High-performance replacement for React Native's FlatList, built on recycling principles. Used by thousands of React Native apps for smooth scrolling with large datasets.

Source Layout

  • src/ — library source code (TypeScript)
  • fixture/react-native/ — React Native test/demo app
  • dist/ — compiled output (NOT auto-rebuilt on branch switch)

Key Constraint

estimatedItemSize does NOT exist as a prop on FlashList. Do not use it, suggest it, or add it.

Build & Test

yarn build          # compile TypeScript to dist/
yarn test --forceExit
yarn type-check
yarn lint

Important: dist/ is NOT rebuilt on branch switch. Always run yarn build after checking out a different branch.

Node Version

Node 22.18.0

Commit & PR Conventions

  • Use conventional commits: fix(scope): description, feat(scope): description
  • Scope examples: layout, hooks, scroll, sticky-headers, recycling, viewability
  • Do NOT include any AI attribution (no Co-Authored-By AI lines, no "Generated by" or "Assisted by" text)
  • PR titles should be under 70 characters and match the commit format
  • Link issues with Fixes #<number> in the commit/PR body

Agent PR Token (MANDATORY)

All agent-raised PRs MUST use SHOPIFY_GH_ACCESS_TOKEN for PR creation. PRs created without this token cannot be merged.

  • On CI: The token is available as $AGENT_PR_TOKEN environment variable in agent workflows.
  • When creating a PR, always use: GH_TOKEN="$AGENT_PR_TOKEN" gh pr create ...
  • The default GITHUB_TOKEN is used for all other operations (issue comments, push, checkout). Only PR creation uses AGENT_PR_TOKEN.
  • Never use bare gh pr create without the GH_TOKEN="$AGENT_PR_TOKEN" prefix — the PR will be unmergeable.

CI Cleanup (MANDATORY)

Before finishing on CI, kill all background processes you started — especially Metro (port 8081). Leftover processes prevent the GitHub Actions job from exiting, causing it to run until timeout and waste CI minutes.

lsof -ti:8081 | xargs kill -9 2>/dev/null || true

Available Skills

Skills are reusable workflows in .claude/skills/. Use them when relevant:

Skill When to use
fix-github-issue Fixing a bug end-to-end: reproduce, diagnose, fix, verify on simulator, PR
raise-pr Creating a PR with proper conventional commit format and no AI attribution
review-and-test Reviewing a PR or branch: unit tests, type-check, lint, device testing, RTL/LTR
triage-issue Classifying an issue (P0/P1/P2), finding duplicates, applying labels
agent-device Interacting with iOS simulator or Android emulator (snapshot-based coordinates)
upgrade-react-native Upgrading the fixture app's React Native version
analyze-feedback Scanning agent workflow feedback artifacts and incorporating learnings into skills

Self-Learning

When you discover something important during a session — a pitfall, a non-obvious behavior, a debugging technique, or a pattern that would save time in the future — update the relevant skill file or this file so the knowledge persists.

What to capture:

  • New pitfalls or edge cases discovered while fixing bugs
  • Debugging techniques that worked (or didn't)
  • Corrections to existing instructions that turned out to be wrong
  • Non-obvious behaviors of FlashList, React Native, or the build system

Where to put it:

  • Bug/fix patterns → fix-github-issue skill (Common Pitfalls section)
  • Testing edge cases → review-and-test skill (Edge Cases section)
  • Device interaction quirks → agent-device skill
  • Project-wide facts → this file (CLAUDE.md)
  • Batch analysis of agent feedback → use the analyze-feedback skill to scan workflow artifacts

How:

  • Include the update in the same PR as the fix (not a separate PR)
  • Keep entries concise — one line per pitfall, with enough context to be useful
  • On CI, only add critical learnings (things that would cause repeated failures). Minor improvements should wait for interactive sessions.