# Project Setup Guide for Claude Code

Step-by-step guide to configuring a repository for Claude Code with guardrails, memory, and GitHub workflow integration.

---

## Directory Structure

After setup, your project should have this structure:

```
your-project/
  .claude/
    CLAUDE.md                       # Main project instructions (or use root CLAUDE.md)
    settings.json                   # Shared project settings (hooks, permissions)
    settings.local.json             # Personal overrides (gitignored)
    rules/                          # Modular, path-scoped instructions
      code-style.md
      testing.md
      security.md
      database.md
    agents/                         # Specialized subagents
      security-reviewer.md
      test-writer.md
    skills/                         # Reusable slash-command workflows
      fix-issue/
        SKILL.md
      review-pr/
        SKILL.md
  .github/
    pull_request_template.md        # PR template
    ISSUE_TEMPLATE/
      bug_report.md                 # Bug report template
      feature_request.md            # Feature request template
    workflows/
      claude.yml                    # GitHub Actions workflow for @claude mentions
  .env.example                      # Environment variable documentation
  .gitignore                        # Must include .claude/settings.local.json
```

---

## Setup Steps

### 1. Initialize CLAUDE.md

Run `/init` in Claude Code to generate a starter CLAUDE.md from your codebase, or copy and customize the template from `CLAUDE_MD_TEMPLATE.md`.

Place it at `.claude/CLAUDE.md` (recommended) or `CLAUDE.md` at the project root.

Key sections to include:
- Build and run commands
- Architecture overview
- Code style rules
- Testing instructions
- Git workflow conventions
- Important constraints

### 2. Configure Project Settings

Copy the settings from `SETTINGS_PROJECT_TEMPLATE.md` to `.claude/settings.json`.

Customize:
- **Permissions**: Allow your standard dev commands, deny destructive operations
- **Hooks**: Configure auto-formatting, destructive command blocking, and notifications
- **Adjust for your stack**: Replace npm/prettier/vitest with your tools

### 3. Configure Local Settings

Copy the settings from `SETTINGS_LOCAL_TEMPLATE.md` to `.claude/settings.local.json`.

Add `.claude/settings.local.json` to `.gitignore`:

```
# Claude Code local settings
.claude/settings.local.json
```

### 4. Add Rules

Create `.claude/rules/` and add topic-specific rule files. See `RULES_TEMPLATE.md` for examples.

Start with:
- `code-style.md` -- language and formatting conventions
- `testing.md` -- test framework and conventions
- `security.md` -- security requirements for sensitive code paths
- `database.md` -- migration and schema conventions (if applicable)

### 5. Add Agents (Optional)

Create `.claude/agents/` and add specialized agent definitions. See `AGENTS_TEMPLATE.md` for examples.

Recommended agents:
- `security-reviewer.md` -- security-focused code review
- `test-writer.md` -- test generation
- `pr-reviewer.md` -- pull request review

### 6. Add Skills (Optional)

Create `.claude/skills/` with workflow directories. See `SKILLS_TEMPLATE.md` for examples.

Recommended skills:
- `fix-issue/SKILL.md` -- end-to-end issue resolution
- `review-pr/SKILL.md` -- PR review workflow

### 7. Set Up GitHub Integration

Install the Claude GitHub App and add the workflow file:
1. Install: https://github.com/apps/claude
2. Add `ANTHROPIC_API_KEY` to repository secrets
3. Copy workflow from `GITHUB_WORKFLOW_TEMPLATE.md` to `.github/workflows/claude.yml`
4. Copy PR template from `PR_TEMPLATE.md` to `.github/pull_request_template.md`
5. Copy issue templates from `ISSUE_BUG_TEMPLATE.md` and `ISSUE_FEATURE_TEMPLATE.md` to `.github/ISSUE_TEMPLATE/`

### 8. Create .env.example

Document all required environment variables:

```bash
# Application
APP_PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Auth
JWT_SECRET=your-jwt-secret-here
SESSION_EXPIRY=3600

# External Services
STRIPE_SECRET_KEY=sk_test_your-key-here
SENDGRID_API_KEY=SG.your-key-here

# Feature Flags
ENABLE_NEW_CHECKOUT=false
```

### 9. Verify the Setup

Run these checks to verify everything is configured correctly:

```bash
# Verify CLAUDE.md exists and is readable
cat .claude/CLAUDE.md

# Verify settings are valid JSON
python3 -c "import json; json.load(open('.claude/settings.json'))"

# Verify .gitignore includes local settings
grep -q "settings.local.json" .gitignore && echo "OK" || echo "MISSING"

# Verify GitHub workflow exists
ls .github/workflows/claude.yml

# Verify issue templates exist
ls .github/ISSUE_TEMPLATE/
```

---

## Gitignore Additions

Add these lines to your `.gitignore`:

```
# Claude Code local settings (personal overrides, not shared)
.claude/settings.local.json
```

---

## Maintenance

- Review and update CLAUDE.md when architecture or conventions change
- Audit hook configurations when switching tools or adding new workflows
- Update permissions when adding new build commands or tools
- Review and prune memory entries periodically
- Keep rules files in sync with evolving coding standards
- Update the GitHub workflow when upgrading the Claude Code action version
