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:
Michael Chihlas
2026-02-03 19:29:30 -05:00
parent cbd8deed32
commit 8498d25efb

View File

@@ -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