Project Initialization

Set up new projects or adopt CLAUDE.md system in existing projects.

Overview

This skill handles two scenarios:

New Projects: Bootstrap from scratch with tech stack selection and configuration
Existing Projects: Analyze codebase and adopt Samuel framework

Both paths result in a fully configured .claude/ directory with project-specific context.

For New Projects

Discovery Process

Ask user these questions to configure the project:

1. Tech Stack

Language: TypeScript, Python, Go, Rust, other?
Framework: React, Django, Express, Axum, other?
Versions: Which versions should we target?

2. Architecture

Monolith (single deployable)
Microservices (multiple services)
Serverless (functions/lambdas)
Jamstack (static + APIs)

3. Testing

Unit test framework?
Integration tests needed?
E2E tests (Playwright, Cypress)?
Coverage targets?

4. Deployment

Cloud: AWS, GCP, Azure, Vercel, Railway?
On-premise servers?
Container platform: Docker, Kubernetes?

5. Database

PostgreSQL, MySQL, MongoDB, SQLite?
ORM/Query builder preferences?
Migrations approach?

6. Additional Requirements

Authentication needed?
API type: REST, GraphQL, gRPC?
Real-time features (WebSockets)?
Background jobs?

Created Artifacts

1. CLAUDE.md Document all tech stack decisions and architecture.

2. Directory Structure Create language-appropriate structure (see references/process.md for templates).

3. Configuration Files Generate:

Language config (tsconfig.json, pyproject.toml, go.mod, Cargo.toml)
Linter config (ESLint, Ruff, golangci-lint, Clippy)
Formatter config (Prettier, Black, gofmt, rustfmt)

4. Essential Files

.gitignore (language-specific)
.env.example (with secure defaults)
README.md (setup instructions)

For Existing Projects

Analysis Process

Automatically scan and analyze:

1. Tech Stack Detection

# Check package managers
ls package.json requirements.txt go.mod Cargo.toml

# Identify language
find . -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rs"

2. Directory Structure Examination

Frontend? (src/, components/, pages/)
Backend? (api/, routes/, controllers/)
Monorepo? (packages/, apps/)
Testing setup? (tests/, tests, *_test.go)

3. Code Pattern Analysis

# Naming conventions
grep -r "function\|class\|interface" src/

# Testing patterns
head -20 tests/*.test.ts

# Database usage
grep -r "SELECT\|INSERT\|UPDATE" src/

4. Git History Review

# Commit message style
git log --pretty=format:"%s" -10

# Branching strategy
git branch -a

5. Existing Tooling Check

Linters: ESLint, Ruff, golangci-lint, Clippy?
Formatters: Prettier, Black, gofmt, rustfmt?
CI/CD: GitHub Actions, GitLab CI, CircleCI?
Testing: Jest, pytest, Go testing, cargo test?

Created Artifacts

1. CLAUDE.md Document discovered tech stack and observed patterns.

Example:

# Project: ExistingApp

## Discovered Tech Stack
- **Language**: TypeScript 5.1
- **Framework**: Next.js 14 (App Router)
- **Database**: PostgreSQL with Prisma ORM
- **Testing**: Jest + React Testing Library
- **Styling**: Tailwind CSS
- **Deployment**: Vercel

## Observed Patterns
- API routes in `app/api/`
- Components use `use client` directive
- Server actions for mutations
- Zod for API validation
- Conventional commits (mostly followed)

## Gaps Identified
- Test coverage: 45% (target: >60%)
- No pre-commit hooks
- ESLint config basic (missing recommended rules)
- Some files exceed 300 lines (needs refactoring)
- Missing .env.example

2. CLAUDE.md Extract coding patterns from existing codebase.

Example:

# Patterns

## API Error Handling
All API routes use this pattern:
\`\`\`typescript
try {
  const data = await validateInput(req.body);
  const result = await service.process(data);
  return NextResponse.json(result);
} catch (error) {
  return handleAPIError(error);
}
\`\`\`

## Database Queries
Always use Prisma with error handling:
\`\`\`typescript
const user = await prisma.user.findUnique({
  where: { id }
}).catch(handlePrismaError);
\`\`\`

3. Gap Analysis & Recommendations

Propose improvements:

Add missing configuration files
Improve test coverage (identify untested modules)
Refactor oversized files (list files >300 lines)
Add pre-commit hooks (husky + lint-staged)
Update dependencies (security patches)
Improve documentation

Adoption Checklist

Confirm with user:

Tech stack correctly identified?
Architecture pattern accurate?
Code conventions match observations?
Testing approach correct?
Any custom patterns AI should know?
Any legacy code to avoid modifying?
Any protected files/directories?

Then proceed to:

Apply guardrails to new code (don't refactor existing immediately)
Suggest incremental improvements
Document conventions in .claude/
Set up recommended tooling (optional)

Post-Initialization

Verify Setup

New Projects:

# Install dependencies
npm install  # or pip install -r requirements.txt

# Run tests (should pass even if empty)
npm test

# Start dev server
npm run dev

# Check linting
npm run lint

Existing Projects:

# Verify .claude/ structure created
ls .claude/

# Read project documentation
cat CLAUDE.md

# Review proposed improvements
cat CLAUDE.md

Next Steps

Review CLAUDE.md
- Confirm tech stack accurate
- Add any missing context
Review CLAUDE.md (if existing project)
- Confirm patterns are correct
- Add any unobserved patterns
Prioritize Improvements (if existing project)
- Security issues: Fix immediately
- Test coverage: Incremental improvement
- Refactoring: Gradual (as you touch files)
- Tooling: Set up recommended tools
Start Development
- AI will now follow guardrails
- AI will load language guide automatically
- AI will reference patterns from .claude/

Common Issues

Dependencies Won't Install

Node.js:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Python:

python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Go:

go clean -modcache
go mod download

Rust:

cargo clean
cargo build

Wrong Version

Use version managers:

# Node.js
nvm install 20 && nvm use 20

# Python
pyenv install 3.11 && pyenv local 3.11

# Go
gvm install go1.21 && gvm use go1.21

# Rust
rustup update stable

AI Not Detecting Tech Stack

Manually specify in CLAUDE.md:

# Project: MyApp

**Tech Stack**: TypeScript + React + Express
**Database**: PostgreSQL
**Testing**: Jest

Then: "I've updated project.md. Please load the appropriate language guide."

Customization

Modify Initial Structure

Edit .claude/skills/initialize-project/SKILL.md to customize:

Default directory structure
Configuration file templates
Questions AI asks
Files AI creates

Add Company Standards

Create .claude/company-standards.md:

# Company Standards

## Required Tools
- ESLint with company config
- Prettier with company config
- Husky for pre-commit hooks

## Required Files
- SECURITY.md
- CONTRIBUTING.md
- LICENSE (MIT)

## Deployment
- All projects deploy to AWS
- Use Terraform for infrastructure
- CI/CD via GitHub Actions

AI will reference this during initialization.

Success Criteria

References

For detailed templates and examples, see:

references/process.md - Full directory structures and configuration templates
CLAUDE.md - Core guardrails and methodology
.claude/skills/{language}-guide/SKILL.md - Language-specific patterns

Remember: Initialization is a one-time setup. The .claude/ directory grows organically as the project evolves. Don't over-document upfront - let patterns emerge naturally.