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

• CLAUDE.md created with accurate tech stack

• CLAUDE.md created (if existing project)

• Directory structure appropriate for language

• Configuration files generated

• .gitignore includes language-specific entries

• .env.example created with secure defaults

• README.md has setup instructions

• Dependencies install successfully

• Tests run (even if empty)

• Dev server starts

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.