Claude Workflow Taming

A comprehensive set of engineering principles and coding standards to guide AI-assisted development across multiple languages and frameworks.

Overview

This skill provides Claude Code with universal engineering principles applicable to all programming languages, plus ecosystem-specific rules for Python/Django and React Native/TypeScript. It emphasizes deep modules, data contracts, semantic failures, and diagnostic discipline.

Instructions

Universal Principles (Apply to All Languages)

1. **Deep Modules**

- Design classes/methods with simple public interfaces that encapsulate complex logic

- Public methods should orchestrate; private methods implement

- Example: `project.build()` or `useAuth()` can be complex internally but must offer simple interfaces

- Goal: Reduce cognitive load for consumers

2. **Data Contracts**

- Never return raw tuples, arrays, or untyped dicts/objects for complex data

- Use structured types (dataclasses, interfaces, types) so consumers access data by name, not index

- Data crossing module boundaries should be structured DTOs, decoupling internal models from public contracts

3. **Semantic Failures**

- Catch low-level technical errors at boundaries and re-raise/transform them as Domain Errors

- Do not catch all exceptions blindly—only catch what you can handle or need to wrap

- Make failures meaningful to the caller's domain

4. **Diagnostic Discipline Protocol**

- **Observe**: What exactly is failing? (error message, stack trace, behavior)

- **Hypothesize**: State your hypothesis explicitly: "I suspect X because Y"

- **Validate**: Use evidence (logs, traces, reproduction, code inspection) to confirm or refute BEFORE coding

- **Minimal Reproduction**: Isolate failure to smallest possible scope

- **Confirm or Pivot**: Did evidence support hypothesis? If not, form new hypothesis

- **Fix**: Only now write the fix addressing the validated root cause

- **Anti-Pattern**: Never assume the cause from symptoms alone. An error message describes WHAT failed, not WHY.

React Native / TypeScript Rules

**Mental Model: The Tao of React**

**Component Principles:**

**State Management:**

**Project Rules:**

1. **Hook Abstraction**: Extract complex logic into custom hooks if component has >3 `useEffect` calls

2. **Props Hygiene**: Use named parameters (objects), discriminated unions for multi-state logic, avoid prop drilling >2 layers

3. **Async Safety**: Handle race conditions, show loading/error states, consider optimistic updates

4. **Styling & Performance**: Use Flexbox only (no hardcoded dimensions), memoize with `React.memo`/`useCallback`, use `FlatList` for long lists

**Code Patterns:**

```typescript

// Custom Hook (Deep Module)

const useUserProfile = (userId: string) => {

const { data, isLoading, error } = useQuery({

queryKey: ['user', userId],

queryFn: () => api.fetchUser(userId)

});

return { user: data, isLoading, isError: !!error };

};

// Named Parameters (Data Contracts)

interface AnimationConfig {

duration: number;

useNativeDriver: boolean;

easing?: 'easeIn' | 'easeOut';

}

// Discriminated Unions (State Hygiene)

type State =

| { status: 'idle' }

| { status: 'loading' }

| { status: 'success'; data: User }

| { status: 'error'; error: string };

// Derived State (Single Source of Truth)

const count = items.length; // Calculate, don't store

```

Python/Django Rules

**The Zen of Python:**

**Django Design Philosophies:**

**Project Rules:**

1. **State Hygiene**: Don't mutate Model instances unless that's the function's purpose; isolate IO from pure logic

2. **Database Sovereignty**: Use `TextChoices` for enums, `UniqueConstraint`/`CheckConstraint` in Meta, wrap multi-step writes in `transaction.atomic()`, default to `on_delete=models.PROTECT`

3. **Coding Style**: Strictly typed signatures, descriptive names, named kwargs for complex calls, use bulk operations (never save in loops)

**Code Patterns:**

```python

State Hygiene: Separate pure logic from IO

def calculate_discount(order: Order) -> Decimal: # Pure

return order.total * Decimal('0.1')

def apply_discount(order: Order) -> None: # Mutation

order.discount = calculate_discount(order)

order.save()

Database Sovereignty: Enums and Constraints

class Order(models.Model):

class Status(models.TextChoices):

PENDING = 'PENDING'

SHIPPED = 'SHIPPED'

status = models.CharField(choices=Status.choices, default=Status.PENDING)

class Meta:

constraints = [

models.CheckConstraint(

check=models.Q(total__gte=0),

name='total_non_negative'

)

]

```

Usage

When working on code:

1. Always apply Diagnostic Discipline before proposing fixes

2. Choose language-specific rules based on the codebase

3. Prioritize Deep Modules and Data Contracts in all architectures

4. Use structured types and semantic errors at boundaries

5. Follow the mental models: UI = f(State) for React, Active Record for Django

Constraints