ISA-Frontend/CLAUDE.md

CLAUDE.md

This file contains meta-instructions for how Claude should work with the ISA-Frontend codebase.

🔴 CRITICAL: Mandatory Agent Usage

You MUST use these subagents for ALL research and knowledge management 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

Violations of this rule degrade performance and context quality. NO EXCEPTIONS.

Communication Guidelines

Keep answers concise and focused:

• Provide direct, actionable responses without unnecessary elaboration
• Skip verbose explanations unless specifically requested
• Focus on what the user needs to know, not everything you know
• Use bullet points and structured formatting for clarity
• Only provide detailed explanations when complexity requires it

Researching and Investigating the Codebase

🔴 MANDATORY: You MUST use subagents for research. Direct file reading/searching.

Required Agent Usage

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

Documentation Research System (Two-Tier)

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

Enforcement Examples

❌ WRONG: Read libs/ui/buttons/README.md
✅ RIGHT: Task → docs-researcher → "Find documentation for @isa/ui/buttons"

❌ WRONG: Grep for "signalStore" patterns
✅ RIGHT: Task → Explore → "Find all signalStore implementations"

❌ WRONG: WebSearch for Zod documentation
✅ RIGHT: Task → docs-researcher → "Find Zod validation documentation"

Remember: Using subagents is NOT optional - it's mandatory for maintaining context efficiency and search quality.

General Guidelines for working with Nx

• When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through nx (i.e. nx run, nx run-many, nx affected) instead of using the underlying tooling directly
• You have access to the Nx MCP server and its tools, use them to help the user
• When answering questions about the repository, use the nx_workspace tool first to gain an understanding of the workspace architecture where applicable.
• When working in individual projects, use the nx_project_details mcp tool to analyze and understand the specific project structure and dependencies
• For questions around nx configuration, best practices or if you're unsure, use the nx_docs tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
• If the user needs help with an Nx configuration or project graph error, use the nx_workspace tool to get any errors