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
|
│ │ │ ├── layout/ # AppLayout, ProtectedRoute
|
||||||
│ │ │ ├── tree-editor/ # Tree editor components
|
│ │ │ ├── tree-editor/ # Tree editor components
|
||||||
│ │ │ ├── tree-preview/ # Visual tree preview
|
│ │ │ ├── tree-preview/ # Visual tree preview
|
||||||
|
│ │ │ ├── step-library/ # Step library browser, forms, modals
|
||||||
│ │ │ └── ui/ # MarkdownContent
|
│ │ │ └── ui/ # MarkdownContent
|
||||||
│ │ ├── pages/
|
│ │ ├── pages/
|
||||||
│ │ │ ├── LoginPage.tsx
|
│ │ │ ├── LoginPage.tsx
|
||||||
@@ -304,6 +305,10 @@ alembic upgrade head
|
|||||||
# Create new migration
|
# Create new migration
|
||||||
alembic revision --autogenerate -m "Description"
|
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)
|
# Access PostgreSQL (no local psql needed)
|
||||||
docker exec -it patherly_postgres psql -U postgres -d patherly
|
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 `cn()` from `@/lib/utils` for Tailwind class merging
|
||||||
- Use Lucide icons (no `title` prop - wrap in `<span>` instead)
|
- Use Lucide icons (no `title` prop - wrap in `<span>` instead)
|
||||||
- Modals: Use fixed header/footer with scrollable body
|
- Modals: Use fixed header/footer with scrollable body
|
||||||
|
- Modals: Import and render at end of parent component JSX
|
||||||
- Forms: Show field-level validation errors
|
- 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
|
### API Client Pattern
|
||||||
|
|
||||||
@@ -544,6 +557,14 @@ const response = await api.get('/api/v1/trees')
|
|||||||
4. Add tests in `backend/tests/`
|
4. Add tests in `backend/tests/`
|
||||||
5. Update API client in `frontend/src/api/`
|
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
|
### Adding a New Page
|
||||||
|
|
||||||
1. Create page component in `frontend/src/pages/`
|
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`
|
- Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
|
||||||
- Always include `Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`
|
- 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
|
## Future Roadmap
|
||||||
|
|||||||
Reference in New Issue
Block a user