From 86b5a53e5d5362201ce8a991e4b5661f649fd642 Mon Sep 17 00:00:00 2001 From: Hor1zonZzz <105845016+Hor1zonZzz@users.noreply.github.com> Date: Thu, 5 Feb 2026 21:58:06 +0800 Subject: [PATCH] refactor(rules): restructure into common + language-specific directories * refactor(rules): restructure rules into common + language-specific directories - Split 8 flat rule files into common/, typescript/, python/, golang/ - common/ contains language-agnostic principles (no code examples) - typescript/ extracts TS/JS specifics (Zod, Playwright, Prettier hooks, etc.) - python/ adds Python rules (PEP 8, pytest, black/ruff, bandit) - golang/ adds Go rules (gofmt, table-driven tests, gosec, functional options) - Replace deprecated ultrathink with extended thinking documentation - Add README.md with installation guide and new-language template Co-Authored-By: Claude Opus 4.5 * Fix installation commands for rules Updated installation instructions to copy all rules to a single directory. * docs: update README.md to reflect new rules directory structure Co-Authored-By: Claude Opus 4.5 --------- Co-authored-by: Hor1zonZzz Co-authored-by: Claude Opus 4.5 --- README.md | 56 ++++++++++++++++-------- rules/README.md | 63 +++++++++++++++++++++++++++ rules/coding-style.md | 70 ------------------------------ rules/{ => common}/agents.md | 4 +- rules/common/coding-style.md | 48 ++++++++++++++++++++ rules/{ => common}/git-workflow.md | 0 rules/{ => common}/hooks.md | 16 ------- rules/common/patterns.md | 31 +++++++++++++ rules/{ => common}/performance.md | 16 +++++-- rules/{ => common}/security.md | 15 ++----- rules/{ => common}/testing.md | 3 +- rules/golang/coding-style.md | 26 +++++++++++ rules/golang/hooks.md | 11 +++++ rules/golang/patterns.md | 39 +++++++++++++++++ rules/golang/security.md | 28 ++++++++++++ rules/golang/testing.md | 25 +++++++++++ rules/python/coding-style.md | 37 ++++++++++++++++ rules/python/hooks.md | 14 ++++++ rules/python/patterns.md | 34 +++++++++++++++ rules/python/security.md | 25 +++++++++++ rules/python/testing.md | 33 ++++++++++++++ rules/typescript/coding-style.md | 58 +++++++++++++++++++++++++ rules/typescript/hooks.md | 15 +++++++ rules/{ => typescript}/patterns.md | 16 ++----- rules/typescript/security.md | 21 +++++++++ rules/typescript/testing.md | 11 +++++ 26 files changed, 580 insertions(+), 135 deletions(-) create mode 100644 rules/README.md delete mode 100644 rules/coding-style.md rename rules/{ => common}/agents.md (94%) create mode 100644 rules/common/coding-style.md rename rules/{ => common}/git-workflow.md (100%) rename rules/{ => common}/hooks.md (55%) create mode 100644 rules/common/patterns.md rename rules/{ => common}/performance.md (65%) rename rules/{ => common}/security.md (74%) rename rules/{ => common}/testing.md (86%) create mode 100644 rules/golang/coding-style.md create mode 100644 rules/golang/hooks.md create mode 100644 rules/golang/patterns.md create mode 100644 rules/golang/security.md create mode 100644 rules/golang/testing.md create mode 100644 rules/python/coding-style.md create mode 100644 rules/python/hooks.md create mode 100644 rules/python/patterns.md create mode 100644 rules/python/security.md create mode 100644 rules/python/testing.md create mode 100644 rules/typescript/coding-style.md create mode 100644 rules/typescript/hooks.md rename rules/{ => typescript}/patterns.md (70%) create mode 100644 rules/typescript/security.md create mode 100644 rules/typescript/testing.md diff --git a/README.md b/README.md index f5074c6..3bf8c98 100644 --- a/README.md +++ b/README.md @@ -83,8 +83,13 @@ Get up and running in under 2 minutes: # Clone the repo first git clone https://github.com/affaan-m/everything-claude-code.git -# Copy rules (applies to all projects) -cp -r everything-claude-code/rules/* ~/.claude/rules/ +# Install common rules (required) +cp -r everything-claude-code/rules/common/* ~/.claude/rules/ + +# Install language-specific rules (pick your stack) +cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ +cp -r everything-claude-code/rules/python/* ~/.claude/rules/ +cp -r everything-claude-code/rules/golang/* ~/.claude/rules/ ``` ### Step 3: Start Using @@ -195,12 +200,19 @@ everything-claude-code/ | |-- evolve.md # /evolve - Cluster instincts into skills (NEW) | |-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/) -| |-- security.md # Mandatory security checks -| |-- coding-style.md # Immutability, file organization -| |-- testing.md # TDD, 80% coverage requirement -| |-- git-workflow.md # Commit format, PR process -| |-- agents.md # When to delegate to subagents -| |-- performance.md # Model selection, context management +| |-- README.md # Structure overview and installation guide +| |-- common/ # Language-agnostic principles +| | |-- coding-style.md # Immutability, file organization +| | |-- git-workflow.md # Commit format, PR process +| | |-- testing.md # TDD, 80% coverage requirement +| | |-- performance.md # Model selection, context management +| | |-- patterns.md # Design patterns, skeleton projects +| | |-- hooks.md # Hook architecture, TodoWrite +| | |-- agents.md # When to delegate to subagents +| | |-- security.md # Mandatory security checks +| |-- typescript/ # TypeScript/JavaScript specific +| |-- python/ # Python specific +| |-- golang/ # Go specific | |-- hooks/ # Trigger-based automations | |-- hooks.json # All hooks config (PreToolUse, PostToolUse, Stop, etc.) @@ -359,11 +371,15 @@ This gives you instant access to all commands, agents, skills, and hooks. > git clone https://github.com/affaan-m/everything-claude-code.git > > # Option A: User-level rules (applies to all projects) -> cp -r everything-claude-code/rules/* ~/.claude/rules/ +> cp -r everything-claude-code/rules/common/* ~/.claude/rules/ +> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # pick your stack +> cp -r everything-claude-code/rules/python/* ~/.claude/rules/ +> cp -r everything-claude-code/rules/golang/* ~/.claude/rules/ > > # Option B: Project-level rules (applies to current project only) > mkdir -p .claude/rules -> cp -r everything-claude-code/rules/* .claude/rules/ +> cp -r everything-claude-code/rules/common/* .claude/rules/ +> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # pick your stack > ``` --- @@ -379,8 +395,11 @@ git clone https://github.com/affaan-m/everything-claude-code.git # Copy agents to your Claude config cp everything-claude-code/agents/*.md ~/.claude/agents/ -# Copy rules -cp everything-claude-code/rules/*.md ~/.claude/rules/ +# Copy rules (common + language-specific) +cp -r everything-claude-code/rules/common/* ~/.claude/rules/ +cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # pick your stack +cp -r everything-claude-code/rules/python/* ~/.claude/rules/ +cp -r everything-claude-code/rules/golang/* ~/.claude/rules/ # Copy commands cp everything-claude-code/commands/*.md ~/.claude/commands/ @@ -448,15 +467,18 @@ Hooks fire on tool events. Example - warn about console.log: ### Rules -Rules are always-follow guidelines. Keep them modular: +Rules are always-follow guidelines, organized into `common/` (language-agnostic) + language-specific directories: ``` -~/.claude/rules/ - security.md # No hardcoded secrets - coding-style.md # Immutability, file limits - testing.md # TDD, coverage requirements +rules/ + common/ # Universal principles (always install) + typescript/ # TS/JS specific patterns and tools + python/ # Python specific patterns and tools + golang/ # Go specific patterns and tools ``` +See [`rules/README.md`](rules/README.md) for installation and structure details. + --- ## ๐Ÿงช Running Tests diff --git a/rules/README.md b/rules/README.md new file mode 100644 index 0000000..3153d60 --- /dev/null +++ b/rules/README.md @@ -0,0 +1,63 @@ +# Rules + +## Structure + +Rules are organized into a **common** layer plus **language-specific** directories: + +``` +rules/ +โ”œโ”€โ”€ common/ # Language-agnostic principles (always install) +โ”‚ โ”œโ”€โ”€ coding-style.md +โ”‚ โ”œโ”€โ”€ git-workflow.md +โ”‚ โ”œโ”€โ”€ testing.md +โ”‚ โ”œโ”€โ”€ performance.md +โ”‚ โ”œโ”€โ”€ patterns.md +โ”‚ โ”œโ”€โ”€ hooks.md +โ”‚ โ”œโ”€โ”€ agents.md +โ”‚ โ””โ”€โ”€ security.md +โ”œโ”€โ”€ typescript/ # TypeScript/JavaScript specific +โ”œโ”€โ”€ python/ # Python specific +โ””โ”€โ”€ golang/ # Go specific +``` + +- **common/** contains universal principles โ€” no language-specific code examples. +- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart. + +## Installation + +```bash +# Install common rules (required for all projects) +cp -r rules/common/* ~/.claude/rules/ + +# Install language-specific rules based on your project's tech stack +cp -r rules/typescript/* ~/.claude/rules/ +cp -r rules/python/* ~/.claude/rules/ +cp -r rules/golang/* ~/.claude/rules/ + +# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only. + +``` + +## Rules vs Skills + +- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets"). +- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`). + +Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it. + +## Adding a New Language + +To add support for a new language (e.g., `rust/`): + +1. Create a `rules/rust/` directory +2. Add files that extend the common rules: + - `coding-style.md` โ€” formatting tools, idioms, error handling patterns + - `testing.md` โ€” test framework, coverage tools, test organization + - `patterns.md` โ€” language-specific design patterns + - `hooks.md` โ€” PostToolUse hooks for formatters, linters, type checkers + - `security.md` โ€” secret management, security scanning tools +3. Each file should start with: + ``` + > This file extends [common/xxx.md](../common/xxx.md) with specific content. + ``` +4. Reference existing skills if available, or create new ones under `skills/`. diff --git a/rules/coding-style.md b/rules/coding-style.md deleted file mode 100644 index 2399d16..0000000 --- a/rules/coding-style.md +++ /dev/null @@ -1,70 +0,0 @@ -# Coding Style - -## Immutability (CRITICAL) - -ALWAYS create new objects, NEVER mutate: - -```javascript -// WRONG: Mutation -function updateUser(user, name) { - user.name = name // MUTATION! - return user -} - -// CORRECT: Immutability -function updateUser(user, name) { - return { - ...user, - name - } -} -``` - -## File Organization - -MANY SMALL FILES > FEW LARGE FILES: -- High cohesion, low coupling -- 200-400 lines typical, 800 max -- Extract utilities from large components -- Organize by feature/domain, not by type - -## Error Handling - -ALWAYS handle errors comprehensively: - -```typescript -try { - const result = await riskyOperation() - return result -} catch (error) { - console.error('Operation failed:', error) - throw new Error('Detailed user-friendly message') -} -``` - -## Input Validation - -ALWAYS validate user input: - -```typescript -import { z } from 'zod' - -const schema = z.object({ - email: z.string().email(), - age: z.number().int().min(0).max(150) -}) - -const validated = schema.parse(input) -``` - -## Code Quality Checklist - -Before marking work complete: -- [ ] Code is readable and well-named -- [ ] Functions are small (<50 lines) -- [ ] Files are focused (<800 lines) -- [ ] No deep nesting (>4 levels) -- [ ] Proper error handling -- [ ] No console.log statements -- [ ] No hardcoded values -- [ ] No mutation (immutable patterns used) diff --git a/rules/agents.md b/rules/common/agents.md similarity index 94% rename from rules/agents.md rename to rules/common/agents.md index d30bcef..e284331 100644 --- a/rules/agents.md +++ b/rules/common/agents.md @@ -31,9 +31,9 @@ ALWAYS use parallel Task execution for independent operations: ```markdown # GOOD: Parallel execution Launch 3 agents in parallel: -1. Agent 1: Security analysis of auth.ts +1. Agent 1: Security analysis of auth module 2. Agent 2: Performance review of cache system -3. Agent 3: Type checking of utils.ts +3. Agent 3: Type checking of utilities # BAD: Sequential when unnecessary First agent 1, then agent 2, then agent 3 diff --git a/rules/common/coding-style.md b/rules/common/coding-style.md new file mode 100644 index 0000000..2ee4fde --- /dev/null +++ b/rules/common/coding-style.md @@ -0,0 +1,48 @@ +# Coding Style + +## Immutability (CRITICAL) + +ALWAYS create new objects, NEVER mutate existing ones: + +``` +// Pseudocode +WRONG: modify(original, field, value) โ†’ changes original in-place +CORRECT: update(original, field, value) โ†’ returns new copy with change +``` + +Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency. + +## File Organization + +MANY SMALL FILES > FEW LARGE FILES: +- High cohesion, low coupling +- 200-400 lines typical, 800 max +- Extract utilities from large modules +- Organize by feature/domain, not by type + +## Error Handling + +ALWAYS handle errors comprehensively: +- Handle errors explicitly at every level +- Provide user-friendly error messages in UI-facing code +- Log detailed error context on the server side +- Never silently swallow errors + +## Input Validation + +ALWAYS validate at system boundaries: +- Validate all user input before processing +- Use schema-based validation where available +- Fail fast with clear error messages +- Never trust external data (API responses, user input, file content) + +## Code Quality Checklist + +Before marking work complete: +- [ ] Code is readable and well-named +- [ ] Functions are small (<50 lines) +- [ ] Files are focused (<800 lines) +- [ ] No deep nesting (>4 levels) +- [ ] Proper error handling +- [ ] No hardcoded values (use constants or config) +- [ ] No mutation (immutable patterns used) diff --git a/rules/git-workflow.md b/rules/common/git-workflow.md similarity index 100% rename from rules/git-workflow.md rename to rules/common/git-workflow.md diff --git a/rules/hooks.md b/rules/common/hooks.md similarity index 55% rename from rules/hooks.md rename to rules/common/hooks.md index d1b891c..5439408 100644 --- a/rules/hooks.md +++ b/rules/common/hooks.md @@ -6,22 +6,6 @@ - **PostToolUse**: After tool execution (auto-format, checks) - **Stop**: When session ends (final verification) -## Current Hooks (in ~/.claude/settings.json) - -### PreToolUse -- **tmux reminder**: Suggests tmux for long-running commands (npm, pnpm, yarn, cargo, etc.) -- **git push review**: Opens Zed for review before push -- **doc blocker**: Blocks creation of unnecessary .md/.txt files - -### PostToolUse -- **PR creation**: Logs PR URL and GitHub Actions status -- **Prettier**: Auto-formats JS/TS files after edit -- **TypeScript check**: Runs tsc after editing .ts/.tsx files -- **console.log warning**: Warns about console.log in edited files - -### Stop -- **console.log audit**: Checks all modified files for console.log before session ends - ## Auto-Accept Permissions Use with caution: diff --git a/rules/common/patterns.md b/rules/common/patterns.md new file mode 100644 index 0000000..959939f --- /dev/null +++ b/rules/common/patterns.md @@ -0,0 +1,31 @@ +# Common Patterns + +## Skeleton Projects + +When implementing new functionality: +1. Search for battle-tested skeleton projects +2. Use parallel agents to evaluate options: + - Security assessment + - Extensibility analysis + - Relevance scoring + - Implementation planning +3. Clone best match as foundation +4. Iterate within proven structure + +## Design Patterns + +### Repository Pattern + +Encapsulate data access behind a consistent interface: +- Define standard operations: findAll, findById, create, update, delete +- Concrete implementations handle storage details (database, API, file, etc.) +- Business logic depends on the abstract interface, not the storage mechanism +- Enables easy swapping of data sources and simplifies testing with mocks + +### API Response Format + +Use a consistent envelope for all API responses: +- Include a success/status indicator +- Include the data payload (nullable on error) +- Include an error message field (nullable on success) +- Include metadata for paginated responses (total, page, limit) diff --git a/rules/performance.md b/rules/common/performance.md similarity index 65% rename from rules/performance.md rename to rules/common/performance.md index f7ef93b..e3284a4 100644 --- a/rules/performance.md +++ b/rules/common/performance.md @@ -30,13 +30,21 @@ Lower context sensitivity tasks: - Documentation updates - Simple bug fixes -## Ultrathink + Plan Mode +## Extended Thinking + Plan Mode + +Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning. + +Control extended thinking via: +- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux) +- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json` +- **Budget cap**: `export MAX_THINKING_TOKENS=10000` +- **Verbose mode**: Ctrl+O to see thinking output For complex tasks requiring deep reasoning: -1. Use `ultrathink` for enhanced thinking +1. Ensure extended thinking is enabled (on by default) 2. Enable **Plan Mode** for structured approach -3. "Rev the engine" with multiple critique rounds -4. Use split role sub-agents for diverse analysis +3. Use multiple critique rounds for thorough analysis +4. Use split role sub-agents for diverse perspectives ## Build Troubleshooting diff --git a/rules/security.md b/rules/common/security.md similarity index 74% rename from rules/security.md rename to rules/common/security.md index a56a4b7..49624c0 100644 --- a/rules/security.md +++ b/rules/common/security.md @@ -14,17 +14,10 @@ Before ANY commit: ## Secret Management -```typescript -// NEVER: Hardcoded secrets -const apiKey = "sk-proj-xxxxx" - -// ALWAYS: Environment variables -const apiKey = process.env.OPENAI_API_KEY - -if (!apiKey) { - throw new Error('OPENAI_API_KEY not configured') -} -``` +- NEVER hardcode secrets in source code +- ALWAYS use environment variables or a secret manager +- Validate that required secrets are present at startup +- Rotate any secrets that may have been exposed ## Security Response Protocol diff --git a/rules/testing.md b/rules/common/testing.md similarity index 86% rename from rules/testing.md rename to rules/common/testing.md index 2244049..fdcd949 100644 --- a/rules/testing.md +++ b/rules/common/testing.md @@ -5,7 +5,7 @@ Test Types (ALL required): 1. **Unit Tests** - Individual functions, utilities, components 2. **Integration Tests** - API endpoints, database operations -3. **E2E Tests** - Critical user flows (Playwright) +3. **E2E Tests** - Critical user flows (framework chosen per language) ## Test-Driven Development @@ -27,4 +27,3 @@ MANDATORY workflow: ## Agent Support - **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first -- **e2e-runner** - Playwright E2E testing specialist diff --git a/rules/golang/coding-style.md b/rules/golang/coding-style.md new file mode 100644 index 0000000..2188453 --- /dev/null +++ b/rules/golang/coding-style.md @@ -0,0 +1,26 @@ +# Go Coding Style + +> This file extends [common/coding-style.md](../common/coding-style.md) with Go specific content. + +## Formatting + +- **gofmt** and **goimports** are mandatory โ€” no style debates + +## Design Principles + +- Accept interfaces, return structs +- Keep interfaces small (1-3 methods) + +## Error Handling + +Always wrap errors with context: + +```go +if err != nil { + return fmt.Errorf("failed to create user: %w", err) +} +``` + +## Reference + +See skill: `golang-patterns` for comprehensive Go idioms and patterns. diff --git a/rules/golang/hooks.md b/rules/golang/hooks.md new file mode 100644 index 0000000..1a85291 --- /dev/null +++ b/rules/golang/hooks.md @@ -0,0 +1,11 @@ +# Go Hooks + +> This file extends [common/hooks.md](../common/hooks.md) with Go specific content. + +## PostToolUse Hooks + +Configure in `~/.claude/settings.json`: + +- **gofmt/goimports**: Auto-format `.go` files after edit +- **go vet**: Run static analysis after editing `.go` files +- **staticcheck**: Run extended static checks on modified packages diff --git a/rules/golang/patterns.md b/rules/golang/patterns.md new file mode 100644 index 0000000..6d219dd --- /dev/null +++ b/rules/golang/patterns.md @@ -0,0 +1,39 @@ +# Go Patterns + +> This file extends [common/patterns.md](../common/patterns.md) with Go specific content. + +## Functional Options + +```go +type Option func(*Server) + +func WithPort(port int) Option { + return func(s *Server) { s.port = port } +} + +func NewServer(opts ...Option) *Server { + s := &Server{port: 8080} + for _, opt := range opts { + opt(s) + } + return s +} +``` + +## Small Interfaces + +Define interfaces where they are used, not where they are implemented. + +## Dependency Injection + +Use constructor functions to inject dependencies: + +```go +func NewUserService(repo UserRepository, logger Logger) *UserService { + return &UserService{repo: repo, logger: logger} +} +``` + +## Reference + +See skill: `golang-patterns` for comprehensive Go patterns including concurrency, error handling, and package organization. diff --git a/rules/golang/security.md b/rules/golang/security.md new file mode 100644 index 0000000..0a118c3 --- /dev/null +++ b/rules/golang/security.md @@ -0,0 +1,28 @@ +# Go Security + +> This file extends [common/security.md](../common/security.md) with Go specific content. + +## Secret Management + +```go +apiKey := os.Getenv("OPENAI_API_KEY") +if apiKey == "" { + log.Fatal("OPENAI_API_KEY not configured") +} +``` + +## Security Scanning + +- Use **gosec** for static security analysis: + ```bash + gosec ./... + ``` + +## Context & Timeouts + +Always use `context.Context` for timeout control: + +```go +ctx, cancel := context.WithTimeout(ctx, 5*time.Second) +defer cancel() +``` diff --git a/rules/golang/testing.md b/rules/golang/testing.md new file mode 100644 index 0000000..ac87e13 --- /dev/null +++ b/rules/golang/testing.md @@ -0,0 +1,25 @@ +# Go Testing + +> This file extends [common/testing.md](../common/testing.md) with Go specific content. + +## Framework + +Use the standard `go test` with **table-driven tests**. + +## Race Detection + +Always run with the `-race` flag: + +```bash +go test -race ./... +``` + +## Coverage + +```bash +go test -cover ./... +``` + +## Reference + +See skill: `golang-testing` for detailed Go testing patterns and helpers. diff --git a/rules/python/coding-style.md b/rules/python/coding-style.md new file mode 100644 index 0000000..c96bba4 --- /dev/null +++ b/rules/python/coding-style.md @@ -0,0 +1,37 @@ +# Python Coding Style + +> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content. + +## Standards + +- Follow **PEP 8** conventions +- Use **type annotations** on all function signatures + +## Immutability + +Prefer immutable data structures: + +```python +from dataclasses import dataclass + +@dataclass(frozen=True) +class User: + name: str + email: str + +from typing import NamedTuple + +class Point(NamedTuple): + x: float + y: float +``` + +## Formatting + +- **black** for code formatting +- **isort** for import sorting +- **ruff** for linting + +## Reference + +See skill: `python-patterns` for comprehensive Python idioms and patterns. diff --git a/rules/python/hooks.md b/rules/python/hooks.md new file mode 100644 index 0000000..0ced0dc --- /dev/null +++ b/rules/python/hooks.md @@ -0,0 +1,14 @@ +# Python Hooks + +> This file extends [common/hooks.md](../common/hooks.md) with Python specific content. + +## PostToolUse Hooks + +Configure in `~/.claude/settings.json`: + +- **black/ruff**: Auto-format `.py` files after edit +- **mypy/pyright**: Run type checking after editing `.py` files + +## Warnings + +- Warn about `print()` statements in edited files (use `logging` module instead) diff --git a/rules/python/patterns.md b/rules/python/patterns.md new file mode 100644 index 0000000..96b96c1 --- /dev/null +++ b/rules/python/patterns.md @@ -0,0 +1,34 @@ +# Python Patterns + +> This file extends [common/patterns.md](../common/patterns.md) with Python specific content. + +## Protocol (Duck Typing) + +```python +from typing import Protocol + +class Repository(Protocol): + def find_by_id(self, id: str) -> dict | None: ... + def save(self, entity: dict) -> dict: ... +``` + +## Dataclasses as DTOs + +```python +from dataclasses import dataclass + +@dataclass +class CreateUserRequest: + name: str + email: str + age: int | None = None +``` + +## Context Managers & Generators + +- Use context managers (`with` statement) for resource management +- Use generators for lazy evaluation and memory-efficient iteration + +## Reference + +See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization. diff --git a/rules/python/security.md b/rules/python/security.md new file mode 100644 index 0000000..d9aec92 --- /dev/null +++ b/rules/python/security.md @@ -0,0 +1,25 @@ +# Python Security + +> This file extends [common/security.md](../common/security.md) with Python specific content. + +## Secret Management + +```python +import os +from dotenv import load_dotenv + +load_dotenv() + +api_key = os.environ["OPENAI_API_KEY"] # Raises KeyError if missing +``` + +## Security Scanning + +- Use **bandit** for static security analysis: + ```bash + bandit -r src/ + ``` + +## Reference + +See skill: `django-security` for Django-specific security guidelines (if applicable). diff --git a/rules/python/testing.md b/rules/python/testing.md new file mode 100644 index 0000000..29a3a66 --- /dev/null +++ b/rules/python/testing.md @@ -0,0 +1,33 @@ +# Python Testing + +> This file extends [common/testing.md](../common/testing.md) with Python specific content. + +## Framework + +Use **pytest** as the testing framework. + +## Coverage + +```bash +pytest --cov=src --cov-report=term-missing +``` + +## Test Organization + +Use `pytest.mark` for test categorization: + +```python +import pytest + +@pytest.mark.unit +def test_calculate_total(): + ... + +@pytest.mark.integration +def test_database_connection(): + ... +``` + +## Reference + +See skill: `python-testing` for detailed pytest patterns and fixtures. diff --git a/rules/typescript/coding-style.md b/rules/typescript/coding-style.md new file mode 100644 index 0000000..333f52d --- /dev/null +++ b/rules/typescript/coding-style.md @@ -0,0 +1,58 @@ +# TypeScript/JavaScript Coding Style + +> This file extends [common/coding-style.md](../common/coding-style.md) with TypeScript/JavaScript specific content. + +## Immutability + +Use spread operator for immutable updates: + +```typescript +// WRONG: Mutation +function updateUser(user, name) { + user.name = name // MUTATION! + return user +} + +// CORRECT: Immutability +function updateUser(user, name) { + return { + ...user, + name + } +} +``` + +## Error Handling + +Use async/await with try-catch: + +```typescript +try { + const result = await riskyOperation() + return result +} catch (error) { + console.error('Operation failed:', error) + throw new Error('Detailed user-friendly message') +} +``` + +## Input Validation + +Use Zod for schema-based validation: + +```typescript +import { z } from 'zod' + +const schema = z.object({ + email: z.string().email(), + age: z.number().int().min(0).max(150) +}) + +const validated = schema.parse(input) +``` + +## Console.log + +- No `console.log` statements in production code +- Use proper logging libraries instead +- See hooks for automatic detection diff --git a/rules/typescript/hooks.md b/rules/typescript/hooks.md new file mode 100644 index 0000000..861d9e5 --- /dev/null +++ b/rules/typescript/hooks.md @@ -0,0 +1,15 @@ +# TypeScript/JavaScript Hooks + +> This file extends [common/hooks.md](../common/hooks.md) with TypeScript/JavaScript specific content. + +## PostToolUse Hooks + +Configure in `~/.claude/settings.json`: + +- **Prettier**: Auto-format JS/TS files after edit +- **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files +- **console.log warning**: Warn about `console.log` in edited files + +## Stop Hooks + +- **console.log audit**: Check all modified files for `console.log` before session ends diff --git a/rules/patterns.md b/rules/typescript/patterns.md similarity index 70% rename from rules/patterns.md rename to rules/typescript/patterns.md index c6970b5..1c5d3da 100644 --- a/rules/patterns.md +++ b/rules/typescript/patterns.md @@ -1,4 +1,6 @@ -# Common Patterns +# TypeScript/JavaScript Patterns + +> This file extends [common/patterns.md](../common/patterns.md) with TypeScript/JavaScript specific content. ## API Response Format @@ -41,15 +43,3 @@ interface Repository { delete(id: string): Promise } ``` - -## Skeleton Projects - -When implementing new functionality: -1. Search for battle-tested skeleton projects -2. Use parallel agents to evaluate options: - - Security assessment - - Extensibility analysis - - Relevance scoring - - Implementation planning -3. Clone best match as foundation -4. Iterate within proven structure diff --git a/rules/typescript/security.md b/rules/typescript/security.md new file mode 100644 index 0000000..5ec60e2 --- /dev/null +++ b/rules/typescript/security.md @@ -0,0 +1,21 @@ +# TypeScript/JavaScript Security + +> This file extends [common/security.md](../common/security.md) with TypeScript/JavaScript specific content. + +## Secret Management + +```typescript +// NEVER: Hardcoded secrets +const apiKey = "sk-proj-xxxxx" + +// ALWAYS: Environment variables +const apiKey = process.env.OPENAI_API_KEY + +if (!apiKey) { + throw new Error('OPENAI_API_KEY not configured') +} +``` + +## Agent Support + +- Use **security-reviewer** skill for comprehensive security audits diff --git a/rules/typescript/testing.md b/rules/typescript/testing.md new file mode 100644 index 0000000..60531af --- /dev/null +++ b/rules/typescript/testing.md @@ -0,0 +1,11 @@ +# TypeScript/JavaScript Testing + +> This file extends [common/testing.md](../common/testing.md) with TypeScript/JavaScript specific content. + +## E2E Testing + +Use **Playwright** as the E2E testing framework for critical user flows. + +## Agent Support + +- **e2e-runner** - Playwright E2E testing specialist