Claude AI Agent Configuration

Maintainer: Hoang Nguyen (hoang.nguyen@angelhack.com)
Tier: Standard

See TIERS.md for tier options: Starter | Standard | Strict

Overview

This project uses Claude AI as an intelligent development agent with structured workflows, specialized sub-agents, and mandatory coding standards.

Development Workflow

Follow this workflow for all feature development:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   /spec  →  /plan  →  /build  →  /test  →  /review  →  Ship│
│                                                             │
│   Define    Plan     Build     Verify    Review     Deploy  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Supporting Commands

Core Principles

Code Quality

• Test-Driven Development — Write failing tests first, then implement
• Incremental Implementation — Small vertical slices, always buildable
• Five-Axis Review — Correctness, Readability, Architecture, Security, Performance

Philosophy

• Progress over perfection
• Fix root causes, not symptoms
• The simplest thing that could work
• Tests are proof, not afterthought

Mandatory Rules

All rules in .claude/rules/ are mandatory and must be followed:

Code Quality

Architecture & Design

Data & Naming

Operations

Language Patterns

Available Agents

Invoke the right agent for each task type:

Development Agents

Quality Agents

Product Agents

Build Resolver Agents

Available Skills

Agent Skills (.agents/skills/)

Open standard skills compatible with 30+ AI agents:

Compile all skills: node scripts/compile-skills.js → generates AGENTS.md

Claude Skills (.claude/skills/)

Specialized skills for complex operations:

Reference Checklists

Quick references in .claude/references/:

Recommended Tools

CodeGraph (Optional)

CodeGraph builds a semantic knowledge graph of codebases, enabling faster and cheaper code exploration.

Benefits:

Setup:

npx @colbymchenry/codegraph init -i

MCP Tools provided:

When to use:

• Large codebases (>10k LOC)
• Architecture exploration ("How does X reach Y?")
• Impact analysis before refactoring
• Understanding call flows

Sensitive Commands Policy

CRITICAL: The following commands must NOT be executed automatically. Instead:

1. Log the command that would run
2. Suggest a safer alternative (if available)
3. Continue workflow — DO NOT block, DO NOT wait for confirmation

Handling Flow

┌─────────────────────────────────────────────────────────────┐
│  Detect sensitive command                                   │
│       ↓                                                     │
│  Log: "⚠️ Sensitive: [command] — using safe alternative"   │
│       ↓                                                     │
│  Execute safe alternative (if available)                    │
│       ↓                                                     │
│  Continue workflow — DO NOT BLOCK                           │
└─────────────────────────────────────────────────────────────┘

Examples

# User requests: "push changes to remote"
# ❌ DON'T: git push --force origin main
# ✅ DO: git push --force-with-lease origin main

# User requests: "clean up old files"
# ❌ DON'T: rm -rf ./tmp/*
# ✅ DO: mkdir -p .trash && mv ./tmp/* .trash/

# User requests: "reset to clean state"
# ❌ DON'T: git reset --hard HEAD
# ✅ DO: git stash -u && git reset --hard HEAD

Hooks System

Automated checks that run before/after tool operations:

See .claude/hooks/README.md for details on creating custom hooks.

MCP Server Configs

Pre-configured MCP servers for common services:

See .claude/mcp-configs/README.md for setup instructions.

Agent Behavior Guidelines

1. Follow the workflow — Use /spec → /plan → /build → /review
2. Apply mandatory rules — All rules in .claude/rules/ are non-negotiable
3. Test first — Write failing tests before implementing
4. Incremental changes — Small commits, always buildable
5. Explain before acting — Describe changes before making them
6. Fix root causes — Don't patch symptoms
7. Use the right agent — Invoke specialized agents for their domains
8. Handle sensitive commands safely — Use alternatives, never block workflow