Optimize AI Coding Agent for Production Team Use

# Install ECC for the scaffolding tools
npm install -g ecc-universal

# Generate a CLAUDE.md for an existing repo
cd your-repo
ecc init  # Interactive wizard

# CLAUDE.md — [Service Name]

## What This Service Does
[2 sentences max. What problem does this solve? Who uses it?]

## Tech Stack
- Language: TypeScript 5.x (strict mode)
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL 16 via Prisma ORM
- Auth: Clerk (not NextAuth — we migrated in Q3 2024)
- Testing: Vitest + Testing Library
- API: tRPC v11 (not REST — we migrated from REST in Q4 2024)

## Architecture
- Monorepo: Turborepo
- Packages: `apps/web`, `apps/api`, `packages/ui`, `packages/db`
- Pattern: Hexagonal architecture (ports and adapters)
- State: Zustand for client state, React Query for server state

## Code Conventions
- No default exports (named exports only)
- Zod for all input validation
- `result-ts` for error handling (not throw/catch)
- Server components by default; client components only when needed
- Never use `any` — use `unknown` and narrow types

## Key Commands
- Dev: `pnpm dev` (from root)
- Test: `pnpm test` (unit), `pnpm test:e2e` (Playwright)
- Lint: `pnpm lint` (must pass before committing)
- DB migration: `pnpm db:migrate` (never edit migration files)

## Rules
- NEVER force push to main/develop/staging
- NEVER modify files in `prisma/migrations/` directly
- NEVER commit .env files with real credentials
- ALWAYS run `pnpm lint && pnpm test` before suggesting a commit
- ALWAYS create a branch for any changes
- Research existing patterns before creating new abstractions

## Recent Decisions (update quarterly)
- 2024-Q4: Migrated REST → tRPC. No new REST endpoints.
- 2024-Q3: Migrated NextAuth → Clerk. Don't reference NextAuth.
- 2024-Q3: Adopted hexagonal architecture. New features go in domain layer.
- 2025-Q1: Switched to Vitest from Jest. Old Jest tests still exist — don't add new ones.

# .github/workflows/claude-md-check.yml
- name: Verify CLAUDE.md
  run: |
    [ -f CLAUDE.md ] || (echo "CLAUDE.md missing!" && exit 1)
    wc -l CLAUDE.md | awk '{if ($1 < 50) {print "CLAUDE.md too short"; exit 1}}'

# Create shared skills repo
mkdir company-claude-skills && cd company-claude-skills
git init
git remote add origin git@github.com:company/claude-skills.git

# Directory structure
mkdir -p skills/{typescript-tdd,api-patterns,database-migrations,deploy-workflow,code-review}

# TypeScript TDD

## When to Use
Any time you're implementing a new feature or fixing a bug.

## Process
1. Read the existing test file for the module (look for `*.test.ts` or `*.spec.ts`)
2. Write a failing test that describes the expected behavior
3. Run `pnpm test --run` to confirm it fails with the right error
4. Write minimal implementation to make the test pass
5. Run full test suite: `pnpm test`
6. Refactor if needed, re-run tests

## Rules
- Test file lives next to source: `src/auth/login.ts` → `src/auth/login.test.ts`
- Mock external services with `vi.mock()` — never hit real APIs
- For database, use the test database: `DATABASE_URL=postgresql://localhost/test_db`
- Aim for behavior tests, not implementation tests

# In each repo's setup script
ln -s ~/company-claude-skills/skills .claude/team-skills

# Add to CLAUDE.md
## Team Skills
Shared team skills: `.claude/team-skills/`
Load these for domain-specific tasks.

# .claude/hooks/session-end.sh
#!/bin/bash
# Auto-captures decisions and file changes at session end

SESSION_FILE=".claude/memory/$(date +%Y-%m-%d).md"
mkdir -p .claude/memory

cat >> "$SESSION_FILE" << EOF
## Session $(date +%H:%M)
Task: ${CLAUDE_TASK:-"Not specified"}
Files modified:
$(git diff --name-only 2>/dev/null | head -20 | sed 's/^/- /')
Key changes:
$(git diff --stat 2>/dev/null | tail -5)
---
EOF

# .claude/memory/DECISIONS.md

## Architecture
- Hexagonal architecture: domain/ contains business logic, adapters/ contains I/O
- All external services go through ports (interfaces), not direct calls

## Libraries
- tRPC for all new API routes (migrated from REST in Q4 2024)
- Clerk for auth (migrated from NextAuth in Q3 2024)
- Prisma for database (never write raw SQL in application code)
- Zod for validation (all external inputs must be validated)

## Testing
- Vitest + Testing Library (replacing old Jest tests over time)
- E2E: Playwright tests in `e2e/` directory
- Coverage threshold: 80% for new code

## Performance
- Server components by default in Next.js
- Client components only for interactive UI
- No client-side data fetching (use React Query or server components)

# Install the plugin for all team members
/plugin marketplace add letta-ai/claude-subconscious
/plugin install claude-subconscious@claude-subconscious

# Set team Letta API key (shared agent per repo)
export LETTA_API_KEY="team-api-key"
export LETTA_MODE="whisper"

# Install AgentShield
npm install -g ecc-agentshield

# Initialize security config
ecc security-init

rules:
  # Git safety
  - id: no-force-push
    description: "Never force push to protected branches"
    pattern: "git push.*--force"
    branches: [main, develop, staging, production]
    severity: critical
    action: block

  - id: require-branch
    description: "Always work on a branch, never commit to main"
    pattern: "git commit.*"
    check: "git branch --show-current | grep -qvE '^(main|develop|staging|production)$'"
    severity: high
    action: warn

  # File operations
  - id: protect-env
    description: "Never read or display .env files"
    pattern: "(cat|read|display|show).*\\.env"
    severity: critical
    action: block

  - id: no-mass-delete
    description: "Require confirmation for directory deletion"
    pattern: "rm -rf [a-zA-Z/]"
    severity: high
    action: require-confirmation

  # Secrets
  - id: no-commit-secrets
    description: "Block commits containing API keys or tokens"
    pre_commit: true
    patterns:
      - "sk-[a-zA-Z0-9]{48}"   # OpenAI
      - "ghp_[a-zA-Z0-9]{36}"  # GitHub PAT
      - "AKIA[0-9A-Z]{16}"     # AWS
    severity: critical
    action: block

# onboarding.sh — run once per developer
ecc security-install --rules company-security-rules.yaml
echo "Security rules installed. Claude Code will now enforce team guardrails."

## CLAUDE.md Rule — Research First (add to all repos)

Before implementing any feature or fix:
1. **Search existing code** — `grep -r "related_term" src/` before creating anything new
2. **Check the skills** — Is there a team skill for this pattern?
3. **Read the module** — Read the header/README of the module you're modifying
4. **Check recent decisions** — Review `.claude/memory/DECISIONS.md`
5. **Then implement** — Following the established patterns

This prevents: reinventing utilities, using deprecated patterns, creating architectural inconsistencies.

# /research command (add to .claude/commands/research.md)
When starting any task:
1. Run: grep -r "${TASK_KEYWORD}" src/ --include="*.ts" | head -20
2. Check: ls .claude/team-skills/ and identify relevant skills
3. Read: The top 2-3 most relevant files found
4. Summarize: What patterns exist that should be followed?
5. Then proceed with implementation

# Add to .claude/hooks/session-end.sh
# Log session metrics to team dashboard

curl -X POST "https://metrics.company.internal/claude-sessions" \
  -H "Content-Type: application/json" \
  -d "{
    \"developer\": \"$(git config user.email)\",
    \"repo\": \"$(basename $(git rev-parse --show-toplevel))\",
    \"task\": \"${CLAUDE_TASK}\",
    \"files_changed\": $(git diff --name-only | wc -l),
    \"session_date\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"completed\": ${CLAUDE_TASK_COMPLETED:-true}
  }"