ar4mirez/initialize-project

Project Initialization

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

---

Overview

This skill handles two scenarios:

1. New Projects: Bootstrap from scratch with tech stack selection and configuration
2. 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

1. Review CLAUDE.md

   • Confirm tech stack accurate
   • Add any missing context

2. Review CLAUDE.md (if existing project)

   • Confirm patterns are correct
   • Add any unobserved patterns

3. Prioritize Improvements (if existing project)

   • Security issues: Fix immediately
   • Test coverage: Incremental improvement
   • Refactoring: Gradual (as you touch files)
   • Tooling: Set up recommended tools

4. 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.