claudekit/.claude/CLAUDE.md

Claude Kit - Project Context Template

Overview

This is a comprehensive Claude Kit for Claude Code, designed to accelerate development workflows for small teams (1-3 developers) working with Python and JavaScript/TypeScript multi-stack projects.

Quick Reference

Key Skills (auto-triggered)

Skill	Triggers on
feature-workflow	"feature", "implement", "build", "add functionality"
systematic-debugging	"bug", "error", "failing", "broken", stack traces
git-workflows	"commit", "PR", "ship", "changelog"
writing-plans	"plan", "break down", "implementation steps"
brainstorming	"brainstorm", "design", "explore", "trade-offs"
documentation	"document", "docstring", "README", "API docs"
refactoring	"refactor", "clean up", "extract", "simplify"
performance-optimization	"slow", "performance", "profiling", "N+1"
mode-switching	"mode", "switch mode", "token-efficient"
session-management	"checkpoint", "index", "load context", "status"

Tech Stack

• Languages: Python, TypeScript, JavaScript
• Backend Frameworks: FastAPI, Django, NestJS, Express
• Frontend Frameworks: Next.js, React
• Databases: PostgreSQL, MongoDB
• Testing: pytest, vitest, Jest, Playwright
• DevOps: Docker, GitHub Actions, Cloudflare

Architecture

src/
├── api/          # API endpoints
├── services/     # Business logic
├── models/       # Data models
├── utils/        # Utilities
└── tests/        # Test files

Code Conventions

Naming Conventions

Type	Python	TypeScript/JavaScript
Files	snake_case.py	kebab-case.ts
Functions	snake_case	camelCase
Classes	PascalCase	PascalCase
Constants	UPPER_SNAKE	UPPER_SNAKE
Components	N/A	PascalCase.tsx

Code Style

• Python: Follow PEP 8, use type hints, docstrings for public APIs
• TypeScript: Strict mode enabled, no any types, use interfaces
• JavaScript: ESLint + Prettier, prefer const over let

File Organization

• One component/class per file
• Group related files in feature directories
• Keep test files adjacent to source files or in tests/ directory

Testing Standards

Coverage Requirements

• Minimum coverage: 80%
• Critical paths: 95%

Test Naming

• Python: test_[function]_[scenario]_[expected]
• TypeScript: describe('[Component]', () => { it('should [behavior]') })

Test Types

1. Unit tests: All business logic functions
2. Integration tests: API endpoints, database operations
3. E2E tests: Critical user flows

Security Standards

Forbidden Patterns

• No hardcoded secrets or API keys
• No eval() or dynamic code execution
• No SQL string concatenation (use parameterized queries)
• No any types in TypeScript
• No disabled security headers

Required Practices

• Input validation on all user inputs
• Output encoding for all rendered content
• Authentication on all protected endpoints
• Rate limiting on public APIs
• Secrets via environment variables only

Git Conventions

Branch Naming

• feature/[ticket]-[description]
• fix/[ticket]-[description]
• hotfix/[description]
• chore/[description]

Commit Messages

type(scope): subject

body (optional)

footer (optional)

Types: feat, fix, docs, style, refactor, test, chore

PR Requirements

• Descriptive title and description
• Linked to issue/ticket
• All tests passing
• Code review approved
• No merge conflicts

Agent Behavior Overrides

Planner Agent

• Break tasks into chunks of 15-60 minutes
• Always identify testing requirements
• Flag external dependencies

Code-Reviewer Agent

• Enforce strict typing
• Security-first reviews
• Check for test coverage

Tester Agent

• Prefer pytest for Python, vitest for TypeScript
• Generate edge case tests
• Include error scenario tests

Debugger Agent

• Check logs first
• Reproduce before fixing
• Add regression tests

Behavioral Modes

Modes adjust communication style, output format, and problem-solving approach.

Mode	Description	Best For
default	Balanced standard behavior	General tasks
brainstorm	Creative exploration, questions	Design, ideation
writing-concisely	Compressed, concise output	High-volume, cost savings
deep-research	Thorough analysis, citations	Investigation, audits
implementation	Code-focused, minimal prose	Executing plans
review	Critical analysis, finding issues	Code review, QA
orchestration	Multi-task coordination	Complex parallel work

Mode Activation

Ask Claude to switch modes naturally:

• "switch to brainstorm mode" → creative exploration
• "use implementation mode" → code-focused, minimal prose
• "switch to token-efficient mode" → compressed output (30-70% savings)

Mode files: .claude/modes/

Token Optimization

Control output verbosity for cost optimization.

Level	Activation	Savings	Description
Standard	(default)	0%	Full explanations
Concise	"be concise"	30-40%	Reduced explanations
Ultra	"code only"	60-70%	Code-only responses
Session	"switch to token-efficient mode"	30-70%	Compressed for session

Reference: .claude/skills/writing-concisely/SKILL.md

Context Management

These features are provided by the session-management skill:

• Project Indexing — "generate a project index" → scans and creates PROJECT_INDEX.md
• Context Loading — "load the API context" → reads relevant files into context
• Checkpoints — "save checkpoint feature-x" → git stash + metadata for session recovery
• Status — "what's the project status?" → git state, tasks, recent commits

MCP Integrations

Optional MCP servers for extended capabilities.

Server	Purpose	Status
Context7	Library documentation lookup	Optional
Sequential	Multi-step reasoning tools	Optional
Playwright	Browser automation (Microsoft)	Optional
Memory	Persistent knowledge graph	Optional
Filesystem	Secure file operations	Optional

Setup: See .claude/mcp/README.md

Methodology Settings

Settings to control the integrated superpowers development methodology.

Planning Granularity

Mode	Task Size	Use Case
standard	15-60 min	Quick planning, experienced team
detailed	2-5 min	Thorough plans with exact code

To use detailed mode: "plan this in detail" or "break this into 2-5 min tasks"

Brainstorming Style

Style	Description
standard	All questions at once
interactive	One question per message with validation

To use interactive mode: "let's brainstorm [topic]"

Execution Mode

Mode	Description
manual	Developer executes tasks from plan
subagent	Automated execution with code review gates

To use subagent mode: "execute the plan" or "run the plan with subagents"

TDD Strictness

For strict TDD enforcement (no production code without failing test):

• Auto-triggers on implementation tasks
• Reference: .claude/skills/test-driven-development/SKILL.md

Verification Requirements

Enable mandatory verification before completion claims:

• Reference: .claude/skills/verification-before-completion/SKILL.md

Available Skills

Category	Skills
Languages	languages (Python, TypeScript, JavaScript)
Backend	backend-frameworks (FastAPI, Django, NestJS, Express)
Frontend	frontend (React, Next.js, shadcn/ui), frontend-styling (Tailwind, accessibility)
Databases	databases (PostgreSQL, MongoDB, Redis, migrations)
DevOps	devops (Docker, GitHub Actions, Cloudflare Workers)
Security	owasp
API	openapi
Testing	testing (pytest, vitest, Jest), playwright
Optimization	writing-concisely, performance-optimization
Developer Patterns	error-handling, state-management, logging, caching, api-client, authentication, background-jobs
Workflows	feature-workflow, git-workflows, documentation, refactoring
Session	mode-switching, session-management
Methodology - Planning	brainstorming, writing-plans, executing-plans, writing-skills
Methodology - Testing	test-driven-development, verification-before-completion, testing-anti-patterns
Methodology - Debugging	systematic-debugging, root-cause-tracing, defense-in-depth
Methodology - Collaboration	dispatching-parallel-agents, requesting-code-review, receiving-code-review, finishing-a-development-branch
Methodology - Execution	subagent-driven-development, using-git-worktrees, condition-based-waiting
Methodology - Reasoning	sequential-thinking

Skills location: .claude/skills/

Each skill includes:

• YAML frontmatter with trigger description
• "When to Use" / "When NOT to Use" sections
• Core patterns with code examples
• Best practices and common pitfalls
• Bundled reference docs, templates, and scripts

Sequential Thinking

For complex problems requiring step-by-step analysis:

• Reference: .claude/skills/sequential-thinking/SKILL.md
• Activation: auto-triggers on complex reasoning tasks, or use deep-research mode

Environment Configuration

Development

# Python
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

# Node.js
pnpm install
pnpm dev

Testing

# Python
pytest -v --cov=src

# Node.js
pnpm test
pnpm test:coverage

Deployment

# Build
pnpm build

# Deploy
pnpm deploy:staging
pnpm deploy:production

External Integrations

APIs

• GitHub API for issue tracking
• Slack for notifications (optional)

Services

• Database: PostgreSQL / MongoDB
• Cache: Redis (optional)
• Storage: S3 / Cloudflare R2

Documentation Standards

Code Documentation

• Public functions: Docstrings required
• Complex logic: Inline comments
• APIs: OpenAPI/Swagger specs

Project Documentation

• README.md: Quick start guide
• CONTRIBUTING.md: Contribution guidelines
• CHANGELOG.md: Version history

Troubleshooting

Common Issues

Python import errors

export PYTHONPATH="${PYTHONPATH}:${PWD}"

Node modules issues

rm -rf node_modules pnpm-lock.yaml
pnpm install

Database connection

• Check .env file for correct credentials
• Ensure database service is running

---

Kit Version

• Claude Kit Version: 3.0.0
• Last Updated: 2026-04-18
• Compatible with: Claude Code 1.0+
• Total Skills: 43 (with YAML frontmatter, bundled resources)
• Total Agents: 20
• Behavioral Modes: 7