project-setup

name	project-setup
description	Best Practices Setup fuer neue Projekte — Testing, Linting, Git Hooks, CI/CD, Security
disable-model-invocation	true

Richte ein neues Projekt mit Best Practices ein. Arbeite inkrementell — nur einrichten was fehlt, nichts ueberschreiben was bereits existiert.

1. Sprache und Framework erkennen

Pruefe welche Dateien im Projektroot existieren, um Sprache und Oekosystem zu bestimmen:

Datei	Oekosystem
package.json	Node.js / TypeScript
pyproject.toml oder requirements.txt	Python
go.mod	Go
Cargo.toml	Rust
pubspec.yaml	Flutter/Dart
composer.json	PHP

Falls keine dieser Dateien existiert: den User fragen welche Sprache/Framework genutzt wird.

Falls package.json existiert, pruefe zusaetzlich:

• vue oder nuxt in dependencies → Vue.js Projekt
• next in dependencies → Next.js Projekt
• react in dependencies → React Projekt
• svelte oder @sveltejs/kit → Svelte/SvelteKit

2. Bestehenden Zustand pruefen

Vor jeder Einrichtung pruefen was schon da ist. Fuer jeden der folgenden Punkte:

• Existiert die Datei/Config bereits? → Ueberspringen oder nur Luecken fuellen
• Gibt es bestehende Patterns? → Diese respektieren und erweitern, nicht ersetzen

Pruefe explizit:

• .gitignore — existiert? Sprachspezifische Eintraege vorhanden?
• .env.example — existiert?
• .env.test — existiert? (Regel aus rules/testing.md beachten)
• Linter-Config — ESLint, Ruff, golangci-lint etc.
• Formatter-Config — Prettier, Black, gofmt etc.
• Test-Framework — Vitest, Jest, pytest, go test etc.
• Git Hooks — Husky, pre-commit, Shell-Scripts in .git/hooks/
• CI/CD — .github/workflows/, .gitlab-ci.yml etc.
• CLAUDE.md — existiert im Projektroot?

3. .gitignore einrichten/erweitern

Falls .gitignore nicht existiert: erstellen. Falls sie existiert: nur fehlende Eintraege ergaenzen.

Immer enthalten:

.env
.env.*
!.env.example
.DS_Store

Sprachspezifisch ergaenzen:

Node.js:

node_modules/
dist/
.next/
.nuxt/
.output/
coverage/
*.tsbuildinfo

Python:

__pycache__/
*.pyc
.venv/
venv/
.mypy_cache/
.ruff_cache/
htmlcov/
.coverage

Go:

bin/
vendor/

Rust:

target/

PHP:

vendor/

4. Environment-Dateien

.env.example

Falls nicht vorhanden: .env.example erstellen mit allen benoetigten Variablen (ohne Werte), basierend auf vorhandenen .env-Dateien oder dem Code. Kommentare hinzufuegen die beschreiben wofuer jede Variable ist.

.env.test

Falls nicht vorhanden und ein E2E-Test-Setup existiert oder geplant ist:

• Template aus ~/.claude/templates/env.test.example kopieren
• .env.test in .gitignore sicherstellen (Regel aus rules/testing.md)

.env.local

Nicht erstellen — das macht der Entwickler selbst. Nur sicherstellen dass .env.local in .gitignore steht.

5. Linting und Formatting einrichten

Nur einrichten falls noch KEIN Linter/Formatter konfiguriert ist.

Node.js / TypeScript

npm install -D eslint prettier eslint-config-prettier

• eslint.config.js (Flat Config, ESLint 9+) erstellen mit sinnvollen Defaults
• .prettierrc erstellen: { "semi": false, "singleQuote": true }
• .prettierignore erstellen mit Build-Outputs
• Falls TypeScript: eslint-plugin-@typescript-eslint ergaenzen
• Scripts in package.json ergaenzen:

  "lint": "eslint .",
  "lint:fix": "eslint . --fix",
  "format": "prettier --write .",
  "format:check": "prettier --check ."
  

Python

pip install ruff  # oder in pyproject.toml als dev-dependency

• [tool.ruff] Sektion in pyproject.toml ergaenzen falls nicht vorhanden
• Ruff-Defaults: line-length = 120, select = ["E", "F", "I", "W"]

Go

• Keine Installation noetig — gofmt und go vet sind built-in
• Optional: golangci-lint empfehlen fuer erweiterte Checks

PHP

composer require --dev squizlabs/php_codesniffer friendsofphp/php-cs-fixer

6. Testing einrichten

Nur einrichten falls noch KEIN Test-Framework konfiguriert ist.

Node.js / TypeScript

Unit Tests — Vitest bevorzugen (bei Vite-Projekten), sonst Jest:

npm install -D vitest @vitest/coverage-v8

• vitest.config.ts erstellen (oder in vite.config.ts integrieren)
• Coverage-Threshold setzen:

  test: {
    coverage: {
      provider: 'v8',
      thresholds: { lines: 80, branches: 80, functions: 80, statements: 80 }
    }
  }
  

• Scripts in package.json:

  "test": "vitest run",
  "test:watch": "vitest",
  "test:coverage": "vitest run --coverage"
  

E2E Tests — Playwright:

npm install -D @playwright/test
npx playwright install

• playwright.config.ts erstellen mit sinnvollen Defaults
• .env.test Credentials nutzen (siehe rules/testing.md)
• tests/ Verzeichnis erstellen falls nicht vorhanden

Python

pip install pytest pytest-cov  # oder als dev-dependency in pyproject.toml

• [tool.pytest.ini_options] in pyproject.toml ergaenzen
• tests/ Verzeichnis erstellen falls nicht vorhanden

Go

• Keine Installation noetig — go test ist built-in
• *_test.go Dateien empfehlen neben dem zu testenden Code

7. Git Hooks einrichten

Nur einrichten falls noch KEINE Git Hooks konfiguriert sind.

Node.js — Husky + lint-staged

npm install -D husky lint-staged
npx husky init

pre-commit Hook (.husky/pre-commit):

npx lint-staged

lint-staged Config in package.json:

"lint-staged": {
  "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
  "*.{json,md,yml,yaml}": ["prettier --write"]
}

pre-push Hook (.husky/pre-push) — nur erstellen falls Tests und Typecheck eingerichtet:

npm run typecheck 2>/dev/null; npm test

package.json Script sicherstellen:

"prepare": "husky"

Python — pre-commit Framework

pip install pre-commit

.pre-commit-config.yaml erstellen:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

pre-commit install

Go / Rust / andere

Einfache Shell-Scripts in .git/hooks/ erstellen:

pre-commit:

#!/bin/sh
# Go: gofmt + go vet
# Rust: cargo fmt --check + cargo clippy

Ausfuehrbar machen: chmod +x .git/hooks/pre-commit

8. CI/CD Pipeline

Nur erstellen falls noch KEINE CI-Config existiert.

Plattform erkennen

• .github/ Verzeichnis → GitHub Actions
• .gitlab-ci.yml → GitLab CI
• Falls unklar: den User fragen

GitHub Actions Template

.github/workflows/ci.yml erstellen mit diesen Stages:

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # === Sprachspezifisch anpassen ===

      # Node.js:
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check
      - run: npx tsc --noEmit  # falls TypeScript
      - run: npm run test:coverage
      - run: npm run build
          

      
      
      
      
      

      
      
      
      

WICHTIG: Nur die Sprach-Bloecke einkommentieren die zum Projekt passen. Die anderen entfernen.

GitLab CI Template

.gitlab-ci.yml analog erstellen mit stages: [lint, test, build].

9. Security Basics

Dependency Scanning

Je nach Oekosystem passenden Audit-Befehl empfehlen und in CI einbauen:

Oekosystem	Befehl
Node.js	npm audit --audit-level=moderate
Python	pip audit (via pip-audit Package)
Go	govulncheck ./...
Rust	cargo audit
PHP	composer audit

Secret Scanning im Pre-commit Hook

Optional empfehlen — nicht automatisch installieren:

• gitleaks — Go-basiert, schnell, gut fuer pre-commit
• detect-secrets — Python-basiert, von Yelp

Dem User die Option vorstellen und nur installieren wenn gewuenscht.

10. Projekt-Dokumentation

CLAUDE.md

Falls nicht vorhanden: CLAUDE.md im Projektroot erstellen mit:

• Projektname und kurze Beschreibung
• Erkannter Tech-Stack
• Wichtige Befehle (dev, build, test, lint)
• Projektstruktur-Ueberblick
• Konventionen (Commit-Style, Branch-Strategie falls erkennbar)

README.md

Falls nicht vorhanden: README.md mit Setup-Anleitung erstellen:

• Voraussetzungen
• Installation
• Development Server starten
• Tests ausfuehren
• Umgebungsvariablen (Verweis auf .env.example)

11. Verifikation

Nach dem Setup alle eingerichteten Tools testen:

# Lint testen
npm run lint  # oder ruff check . oder golangci-lint run

# Formatter testen
npm run format:check  # oder ruff format --check . oder gofmt -l .

# Tests testen (falls Tests existieren)
npm test  # oder pytest oder go test ./...

# Git Hook testen
echo "test" >> /dev/null && git add -A && git diff --cached --stat
# (nur pruefen dass der Hook greift, nicht tatsaechlich committen)

Ergebnisse dem User zeigen. Bei Fehlern: beheben oder erklaeren warum sie auftreten.

12. Zusammenfassung

Am Ende dem User eine Uebersicht zeigen:

Projekt-Setup Zusammenfassung:
- Sprache/Framework: [erkannt]
- .gitignore: [erstellt/erweitert/bereits vorhanden]
- .env.example: [erstellt/bereits vorhanden]
- Linting: [ESLint/Ruff/...] [eingerichtet/bereits vorhanden]
- Formatting: [Prettier/Ruff/...] [eingerichtet/bereits vorhanden]
- Tests: [Vitest/pytest/...] [eingerichtet/bereits vorhanden]
- Git Hooks: [Husky/pre-commit/...] [eingerichtet/bereits vorhanden]
- CI/CD: [GitHub Actions/GitLab CI] [erstellt/bereits vorhanden]
- CLAUDE.md: [erstellt/bereits vorhanden]
- README.md: [erstellt/bereits vorhanden]