docs: Update CLAUDE.md with Step Library implementation learnings
Added concise guidance from Workstream B implementation session: **Database Operations:** - Manual migration creation workflow without running DB - Safe to commit migrations before local testing **Frontend Patterns:** - Modal placement at end of parent component JSX - Conditional rendering null checks pattern - NEW: TypeScript Type Organization section - Type module creation in types/ directory - Export patterns from types/index.ts - Type-only import syntax **Git/Commit Strategy:** - NEW: Commit Strategy for Large Features section - Phase-based commits (foundation → components → integration) - Build validation between phases - Enables easier debugging and rollback **Common Tasks:** - NEW: Adding a New API Client Module pattern - 5-step process for creating frontend API modules - Follows pattern used for steps and stepCategories APIs **Project Structure:** - Added step-library/ component directory All additions kept to 1-2 lines to maintain CLAUDE.md brevity. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
28
CLAUDE.md
28
CLAUDE.md
@@ -158,6 +158,7 @@ patherly/
|
||||
│ │ │ ├── layout/ # AppLayout, ProtectedRoute
|
||||
│ │ │ ├── tree-editor/ # Tree editor components
|
||||
│ │ │ ├── tree-preview/ # Visual tree preview
|
||||
│ │ │ ├── step-library/ # Step library browser, forms, modals
|
||||
│ │ │ └── ui/ # MarkdownContent
|
||||
│ │ ├── pages/
|
||||
│ │ │ ├── LoginPage.tsx
|
||||
@@ -304,6 +305,10 @@ alembic upgrade head
|
||||
# Create new migration
|
||||
alembic revision --autogenerate -m "Description"
|
||||
|
||||
# Create migration without DB running (manual mode)
|
||||
alembic revision -m "Description" # Edit migration file manually
|
||||
# Migration runs when DB is available - safe to commit without testing locally
|
||||
|
||||
# Access PostgreSQL (no local psql needed)
|
||||
docker exec -it patherly_postgres psql -U postgres -d patherly
|
||||
```
|
||||
@@ -521,7 +526,15 @@ interface Decision {
|
||||
- Use `cn()` from `@/lib/utils` for Tailwind class merging
|
||||
- Use Lucide icons (no `title` prop - wrap in `<span>` instead)
|
||||
- Modals: Use fixed header/footer with scrollable body
|
||||
- Modals: Import and render at end of parent component JSX
|
||||
- Forms: Show field-level validation errors
|
||||
- Conditional rendering: Add null checks when node might not exist (`currentNode && currentNode.type`)
|
||||
|
||||
### TypeScript Type Organization
|
||||
|
||||
- New type modules: Create in `types/` directory (e.g., `types/step.ts`)
|
||||
- Export from `types/index.ts` with `export * from './modulename'`
|
||||
- Import types using `import type { Type } from '@/types'` (type-only import)
|
||||
|
||||
### API Client Pattern
|
||||
|
||||
@@ -544,6 +557,14 @@ const response = await api.get('/api/v1/trees')
|
||||
4. Add tests in `backend/tests/`
|
||||
5. Update API client in `frontend/src/api/`
|
||||
|
||||
### Adding a New API Client Module (Frontend)
|
||||
|
||||
1. Create types in `frontend/src/types/modulename.ts`
|
||||
2. Export types from `frontend/src/types/index.ts`
|
||||
3. Create API client in `frontend/src/api/modulename.ts` following existing pattern
|
||||
4. Export from `frontend/src/api/index.ts`
|
||||
5. Import in components: `import { moduleApi } from '@/api'`
|
||||
|
||||
### Adding a New Page
|
||||
|
||||
1. Create page component in `frontend/src/pages/`
|
||||
@@ -583,6 +604,13 @@ const response = await api.get('/api/v1/trees')
|
||||
- Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
|
||||
- Always include `Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`
|
||||
|
||||
### Commit Strategy for Large Features
|
||||
|
||||
- Break implementation into logical phases (foundation → components → integration)
|
||||
- Commit after each phase with `npm run build` validation
|
||||
- Phase commits enable easier debugging and rollback
|
||||
- Example: API clients (Phase 1) → UI components (Phase 2) → Page integration (Phase 3)
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
Reference in New Issue
Block a user