Claude Code Guide

Operational guide for Claude Code sessions working in the jjk-workspace monorepo.

Quick Commands

npm run dev                        # Build content + serve blog (port 4202)
npm run build                      # Build content + build frontend
npm test                           # All tests (frontend + functions)
npm run test:frontend              # Frontend tests only (Vitest + Angular)
npm run test:functions             # Cloud Functions tests only (Vitest + DI mocks)
npx ng build frontend              # Build blog only
npx firebase deploy --only hosting:blog       # Deploy blog
npx firebase deploy --only functions          # Deploy functions only
cd infra && terraform plan                    # Drift check
cd infra && terraform apply                   # Apply infra changes
npm run adr:new "Title"            # Scaffold a new ADR
npm run adr:validate               # Validate ADR format
npm run adr:toc                    # Regenerate ADR index

Pre-Code Checklist

Before creating any new interface, utility, constant, or service:

  1. Check shared/ barrels first:
    • Interfaces/types → shared/models/index.ts (@jjk/models)
    • Utility functions → shared/utils/index.ts (@jjk/utils)
    • Constants → shared/constants/index.ts (@jjk/constants)
    • Services → shared/services/index.ts (@jjk/services)
    • Frontend shared → frontend/src/app/shared/ (@app/shared/*)
    • Copy/content → frontend/src/app/content/copy.ts (@app/content)
  2. Grep before you build. Search for existing implementations.
  3. If it belongs in shared/, put it there from the start.
  4. Check Design Principles for governing patterns.
  5. Check Project Spec for architectural constraints.
  6. Check ADRs for prior decisions. If a change contradicts an existing ADR, surface the conflict first.

Naming Conventions

Element Convention Example
Components feature-name.component.ts post-card.component.ts
Services feature-name.service.ts ratings.service.ts
Component selectors jjk- prefix jjk-post-card, jjk-nav
CSS custom properties --jjk- prefix --jjk-color-ink, --jjk-space-4
Firestore collections snake_case inbox_messages, rate_limits

Key Patterns

  • ViewEncapsulation.None required on any component rendering pre-compiled HTML via [innerHTML]. Scope styles with .jjk-prose class prefix.
  • All user-facing strings in frontend/src/app/content/copy.json. Import via COPY from @app/content.
  • One component per file, co-located template and styles (inline).

ADR Governance

New ADR warranted when:

  • Introducing a new external vendor or service
  • Creating a new data flow pattern or boundary rule
  • Changing how packages depend on each other
  • Adopting a new framework or major library
  • Reversing or amending a prior ADR

NOT needed for: Bug fixes, routine features, version bumps, cosmetic refactors.