sxhundred/ISA-Frontend
1
0
Fork 0
mirror of https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend synced 2025-12-28 22:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: add Claude Code infrastructure and documentation system

Browse Source 
Add comprehensive Claude Code tooling:
- Agents: docs-researcher, docs-researcher-advanced for documentation research
- Commands: dev:add-e2e-attrs, docs:library, docs:refresh-reference, quality:bundle-analyze, quality:coverage
- Skills: 8 specialized skills including api-change-analyzer, architecture-enforcer, library-scaffolder, and more

Update documentation:
- Comprehensive CLAUDE.md overhaul with library reference system
- Update testing guidelines in docs/guidelines/testing.md
- Update READMEs for checkout, icons, scanner, and scroll-position libraries

Remove outdated checkout-completion-flow-documentation.md

Update .gitignore for Claude Code files
This commit is contained in:
Lorenz Hilpert
2025-10-22 15:02:53 +02:00
parent 664c36a9a3
commit bcb412e48d
28 changed files with 4956 additions and 1238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
CLAUDE.md
View File

@@ -6,6 +6,16 @@
> **Node.js:** ≥22.0.0
> **npm:** ≥10.0.0
## 🔴 CRITICAL: Mandatory Agent Usage
**You MUST use these subagents for ALL research tasks:**
- **`docs-researcher`**: For ALL documentation (packages, libraries, READMEs)
- **`docs-researcher-advanced`**: Auto-escalate when docs-researcher fails
- **`Explore`**: For ALL code pattern searches and multi-file analysis
- **Direct tools (Read/Bash)**: ONLY for single specific files or commands
**Violations of this rule degrade performance and context quality. NO EXCEPTIONS.**
## Project Overview
This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main application is `isa-app`, a comprehensive inventory and returns management system for retail/e-commerce operations. The system handles complex workflows including order management (OMS), returns processing (remission), customer relationship management (CRM), product cataloging, and checkout/reward systems.
@@ -32,7 +42,7 @@ This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main a
- **Standalone Components**: All new components use Angular standalone architecture with explicit imports
- **Feature Libraries**: Domain features organized as separate libraries (e.g., `oms-feature-return-search`, `remission-feature-remission-list`)
- **Data Access Layer**: Separate data-access libraries for each domain with NgRx Signals stores
- **Shared UI Components**: 18 dedicated UI component libraries with design system integration
- **Shared UI Components**: 17 dedicated UI component libraries with design system integration
- **Generated API Clients**: 10 auto-generated Swagger/OpenAPI clients with post-processing pipeline
- **Path Aliases**: Comprehensive TypeScript path mapping (`@isa/domain/layer/feature`)
- **Component Prefixes**: Domain-specific prefixes (OMS: `oms-feature-*`, Remission: `remi-*`, UI: `ui-*`)
@@ -96,9 +106,9 @@ npx nx affected:test --skip-nx-cache
> **Status:** Migration in Progress (Jest → Vitest)
### Current Setup (Migration in Progress)
- **Jest**: 31 libraries (legacy/existing code)
- **Vitest**: 10 libraries (new standard)
- **No test executor**: 20 libraries (mostly feature/shared components)
- **Jest**: 40 libraries (65.6% - legacy/existing code)
- **Vitest**: 21 libraries (34.4% - new standard)
- All formal libraries now have test executors configured
### Testing Strategy
- **New libraries**: Use Vitest + Angular Testing Utilities (TestBed, ComponentFixture)
@@ -135,7 +145,7 @@ npx nx affected:test --skip-nx-cache
- **Brand Color System**: `isa-*` color palette with semantic naming
- **Custom Tailwind Plugins** (7): button, typography, menu, label, input, section, select-bullet
- **Typography System**: 14 custom utilities (`.isa-text-heading-1-bold`, `.isa-text-body-2-regular`, etc.)
- **UI Component Libraries**: 18 specialized libraries with consistent APIs (see Library Reference)
- **UI Component Libraries**: 17 specialized libraries with consistent APIs (see Library Reference)
- **Storybook**: Component documentation and development at `npm run storybook`
### Responsive Design with Breakpoint Service
@@ -252,115 +262,71 @@ isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.Deks
### Researching and Investigating the Codebase
**🚨 CRITICAL: Always Research Before Implementation**
**🔴 MANDATORY: You MUST use subagents for research. Direct file reading/searching is FORBIDDEN except for single specific files.**
**NEVER assume you know the answer - AI models are never up-to-date:**
- Before working on ANY problem, research the needed information and documentation
- Even if you think you know how something works, verify with current documentation
- Use `docs-researcher` to check library READMEs, `/docs` files, and API documentation
- Use `Explore` to verify how similar features are currently implemented
- Your training data has a cutoff - the actual codebase is the source of truth
#### Required Agent Usage
**🚨 CRITICAL: Keep Main Context Clean - Always Use Subagents**
| Task Type | Required Agent | Escalation Path |
|-----------|---------------|-----------------|
| **Package/Library Documentation** | `docs-researcher` | → `docs-researcher-advanced` if not found |
| **Internal Library READMEs** | `docs-researcher` | Keep context clean |
| **Code Pattern Search** | `Explore` | Set thoroughness level |
| **Implementation Analysis** | `Explore` | Multiple file analysis |
| **Single Specific File** | Read tool directly | No agent needed |
**When to use `docs-researcher` subagent:**
- Reading and analyzing library READMEs
- Searching and extracting information from `/docs` directory
- Analyzing library documentation when unclear
- Understanding API documentation and usage patterns
- Any documentation-heavy research task
#### Documentation Research System (Two-Tier)
**When to use `Explore` subagent:**
- Searching for patterns across the codebase
- Finding similar implementations
- Exploring component structures
- Discovering how features are implemented
- Any task requiring multiple file reads/searches
1. **ALWAYS start with `docs-researcher`** (Haiku, 30-120s) for any documentation need
2. **Auto-escalate to `docs-researcher-advanced`** (Sonnet, 2-7min) when:
- Documentation not found
- Conflicting sources
- Need code inference
- Complex architectural questions
**General Approach:**
1. **ALWAYS research first** - Never assume you know the answer, verify with current documentation
2. **Start with the Library Reference Guide** (see below) for quick library lookup
3. **Use `docs-researcher` for ALL documentation research** - Keeps main context clean
4. **Use `Explore` for codebase exploration** - Prevents context pollution during searches
5. **Use Nx tools for architecture visualization** - `npx nx graph` to understand dependencies
6. **Follow error messages** - TypeScript/runtime errors point to exact locations
#### Enforcement Examples
**Finding Information by Type:**
| What are you looking for? | Where to search | How |
|---------------------------|-----------------|-----|
| **A specific library's purpose** | Library Reference Guide (below) | Look up by domain/name |
| **How to use a library** | `libs/[domain]/[layer]/[feature]/README.md` | **Use `docs-researcher` subagent** |
| **Project guidelines** | `/docs` directory | **Use `docs-researcher` subagent** |
| **Project dependencies** | `npx nx graph` | Visualize which projects depend on which |
| **Similar existing implementations** | Across codebase | **Use `Explore` subagent** to find patterns |
| **Component structure** | Domain-specific feature folders | **Use `Explore` subagent** for deep dives |
| **State management patterns** | `libs/[domain]/data-access/` | **Use `Explore` subagent** to find stores |
| **API integration examples** | `generated/swagger/` + data-access | **Use `Explore` subagent** to find usage |
| **Styling/Design tokens** | `tailwind.config.js` + `tailwind-plugins/` | **Use `Explore` subagent** for patterns |
| **Error handling patterns** | `libs/common/data-access/` | **Use `Explore` subagent** to find operators |
| **UI components** | `libs/ui/[component]/README.md` | **Use `docs-researcher` or Storybook** |
**Effective Subagent Usage:**
**Using `docs-researcher` subagent (for documentation):**
```
Task: Read and analyze README.md for @isa/[domain]/[layer]/[feature]
Focus on: Purpose, main exports, usage patterns, dependencies, examples
❌ WRONG: Read libs/ui/buttons/README.md
✅ RIGHT: Task → docs-researcher → "Find documentation for @isa/ui/buttons"
Task: Search /docs for testing guidelines
Focus on: Extract relevant sections about Jest/Vitest migration
❌ WRONG: Grep for "signalStore" patterns
✅ RIGHT: Task → Explore → "Find all signalStore implementations"
Task: Analyze library documentation when API is unclear
Focus on: Clarify usage patterns, parameters, return types
❌ WRONG: WebSearch for Zod documentation
✅ RIGHT: Task → docs-researcher → "Find Zod validation documentation"
```
**Using `Explore` subagent (for codebase):**
```
Task: Find all implementations of error handling patterns
Thoroughness: "medium" or "very thorough" depending on complexity
**Remember: Using subagents is NOT optional - it's mandatory for maintaining context efficiency and search quality.**
Task: Search for similar component structures in remission domain
Thoroughness: "medium"
#### Common Research Patterns
Task: Discover how NgRx Signals stores are used across data-access libraries
Thoroughness: "very thorough"
```
| Information Need | Required Approach |
|-----------------|-------------------|
| **Library documentation** | `docs-researcher` → Check library-reference.md → Escalate if needed |
| **Code patterns/examples** | `Explore` with "medium" or "very thorough" |
| **Architecture understanding** | `npx nx graph` + `Explore` for implementation |
| **Debugging/errors** | Direct tool use (Read specific error file, check console) |
**Using Nx tools (for architecture):**
```
- Run: npx nx graph --filter=[project-name]
- Look at which projects this one depends on (imports from)
- Look at which projects depend on it (things that import from it)
- This shows you the dependency chain and data flow
```
**Debugging Tips:**
- **TypeScript errors**: Follow the error path - it points to the exact file and line
- **Runtime errors**: Check browser console (F12) and network tab for API issues
- **Test failures**: Use `--skip-nx-cache` to get fresh test output with full error details
- **Module resolution**: Check `tsconfig.base.json` path aliases to understand import resolution
- **State issues**: Use Angular DevTools browser extension to inspect NgRx state
#### Debugging Tips
- **TypeScript errors**: Follow error path to exact file:line
- **Test failures**: Use `--skip-nx-cache` for fresh output
- **Module resolution**: Check `tsconfig.base.json` path aliases
- **State issues**: Use Angular DevTools browser extension
### Library Development Patterns
- **Understanding Internal Libraries**: Before using any internal library from the `libs/` directory, always read its README.md file using the **`docs-researcher` subagent** to understand its purpose, API, and proper usage patterns
- **Library Documentation**: All libraries have comprehensive README.md documentation. **To keep main context clean, ALWAYS use the `docs-researcher` subagent** to retrieve and analyze library documentation rather than reading files directly
- **Library Documentation**: Use `docs-researcher` for ALL library READMEs (mandatory for context management)
- **New Library Creation**: Use Nx generators with domain-specific naming (`[domain]-[layer]-[feature]`)
- **Standalone Components**: All new components must be standalone with explicit imports - no more NgModules
- **Testing Framework Selection**:
- **New libraries**: Use Vitest + Angular Testing Utilities
- **Existing libraries**: Continue with Jest + Spectator until migrated
- **Path Aliases**: Always use `@isa/[domain]/[layer]/[feature]` - avoid relative imports across domain boundaries
- **Standalone Components**: All new components must be standalone with explicit imports - no NgModules
- **Testing Framework**: New = Vitest + Angular Testing Utilities, Legacy = Jest + Spectator
- **Path Aliases**: Always use `@isa/[domain]/[layer]/[feature]` - avoid relative imports
#### Library Reference Guide
The monorepo contains **61 libraries** organized across 12 domains. For quick lookup of any library's purpose and location, see **[`docs/library-reference.md`](docs/library-reference.md)**.
The monorepo contains **62 libraries** organized across 12 domains. For quick lookup, see **[`docs/library-reference.md`](docs/library-reference.md)**.
**Quick Overview by Domain:**
- Availability (1) | Catalogue (1) | Checkout (6) | Common (3) | Core (5) | CRM (1) | Icons (1)
- OMS (9) | Remission (8) | Shared Components (7) | UI Components (16) | Utilities (3)
**IMPORTANT: Always use the `docs-researcher` subagent** to retrieve and analyze library documentation from `libs/[domain]/[layer]/[feature]/README.md`. This keeps the main context clean and prevents pollution
- OMS (9) | Remission (8) | Shared Components (7) | UI Components (17) | Utilities (3)
### API Integration Workflow
- **Swagger Generation**: Run `npm run generate:swagger` to regenerate all 10 API clients when backend changes