Part 2: Global Rules for New Project Scaffolding

This is where global CLAUDE.md becomes a project factory. Every new project you create automatically inherits your standards, structure, and safety requirements.

The Problem Without Scaffolding Rules

Research from project scaffolding experts explains:

"LLM-assisted development fails by silently expanding scope, degrading quality, and losing architectural intent."

Without global scaffolding rules:

• Each project has different structures
• Security files get forgotten (.gitignore, .dockerignore)
• Error handling is inconsistent
• Documentation patterns vary
• You waste time re-explaining the same requirements

The Solution: Scaffolding Rules in Global CLAUDE.md

Add a "New Project Setup" section to your global file:

## New Project Setup

When creating ANY new project, ALWAYS do the following:

### 1. Required Files (Create Immediately)
- `.env` — Environment variables (NEVER commit)
- `.env.example` — Template with placeholder values
- `.gitignore` — Must include: .env, .env.*, node_modules/, dist/, .claude/
- `.dockerignore` — Must include: .env, .git/, node_modules/
- `README.md` — Project overview (reference env vars, don't hardcode)

### 2. Required Directory Structure
```
project-root/
├── src/               # Source code
├── tests/             # Test files
├── docs/              # Documentation (gitignored for generated docs)
├── .claude/           # Claude configuration
│   ├── commands/      # Custom slash commands
│   └── settings.json  # Project-specific settings
└── scripts/           # Build/deploy scripts
```

### 3. Required .gitignore Entries
```
# Environment
.env
.env.*
.env.local

# Dependencies
node_modules/
vendor/
__pycache__/

# Build outputs
dist/
build/
.next/

# Claude local files
.claude/settings.local.json
CLAUDE.local.md

# Generated docs
docs/*.generated.*
```

### 4. Node.js Projects — Required Error Handling
Add to entry point (index.ts, server.ts, app.ts):
```javascript
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  process.exit(1);
});

process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  process.exit(1);
});
```

### 5. Required CLAUDE.md Sections
Every project CLAUDE.md must include:
- Project overview (what it does)
- Tech stack
- Build commands
- Test commands
- Architecture overview

Why This Works

When you tell Claude "create a new Node.js project," it reads your global CLAUDE.md first and automatically:

1. Creates .env and .env.example
2. Sets up proper .gitignore with all required entries
3. Creates the directory structure
4. Adds error handlers to the entry point
5. Generates a project CLAUDE.md with required sections

You never have to remember these requirements again.

Advanced: Framework-Specific Rules

## Framework-Specific Setup

### Next.js Projects
- Use App Router (not Pages Router)
- Create `src/app/` directory structure
- Include `next.config.js` with strict mode enabled
- Add analytics to layout.tsx

### Python Projects
- Create `pyproject.toml` (not setup.py)
- Use `src/` layout
- Include `requirements.txt` AND `requirements-dev.txt`
- Add `.python-version` file

### Docker Projects
- Multi-stage builds ALWAYS
- Never run as root (use non-root user)
- Include health checks
- `.dockerignore` must mirror `.gitignore` + include `.git/`

Quality Gates in Scaffolding

The claude-project-scaffolding approach adds enforcement:

## Quality Requirements

### File Size Limits
- No file > 300 lines (split if larger)
- No function > 50 lines

### Required Before Commit
- All tests pass
- TypeScript compiles with no errors
- Linter passes with no warnings
- No secrets in staged files

### CI/CD Requirements
Every project must include:
- `.github/workflows/ci.yml` for GitHub Actions
- Pre-commit hooks via Husky (Node.js) or pre-commit (Python)

Example: What Happens When You Create a Project

You say: "Create a new Next.js e-commerce project called shopify-clone"

Claude reads global CLAUDE.md and automatically creates:

shopify-clone/
├── .env                          ← Created (empty, for secrets)
├── .env.example                  ← Created (with placeholder vars)
├── .gitignore                    ← Created (with ALL required entries)
├── .dockerignore                 ← Created (mirrors .gitignore)
├── README.md                     ← Created (references env vars)
├── CLAUDE.md                     ← Created (with required sections)
├── src/
│   └── app/                      ← App Router structure
├── tests/
├── docs/
├── .claude/
│   ├── commands/
│   └── settings.json
└── scripts/

Zero manual setup. Every project starts secure and consistent.