Dev Guardrails

Dev Guardrails

This skill exists because LLMs consistently make a set of predictable, preventable mistakes during development tasks. These guardrails are not suggestions — they are corrective constraints derived from real failure patterns. The goal is to eliminate regressions, preserve existing work, ensure every change is deliberate, tested, context-aware, and coherent with the product as a whole.

Read this entire file before writing any code or making any changes. Then read the relevant reference files in references/ based on the task at hand.

Core Philosophy

Every change you make exists within a living system. Code is not isolated — it connects to other files, services, databases, user flows, and real humans using the product. A single edit can cascade through an entire architecture. Your job is not just to make something work in isolation, but to make it work within the whole system without breaking what already exists.

Think like a senior engineer AND a product owner maintaining a production system with real users and real data, not like an assistant generating code snippets.

Every feature exists within a product that humans use. Before writing code, ask: "Does this make sense to a user? Is this consistent with how the rest of the product works? Would a human product designer approve this? Does this work with the data that already exists in production?"

Session Start Protocol

At the beginning of every new session on a project, before any task execution:

1. Read the project root with view to understand current structure
2. Read core documentation: TODO.md, ARCHITECTURE.md, CHANGELOG.md, README.md (whichever exist)
3. Check recent git history (git log --oneline -20) to understand what changed recently
4. Read any .env.example to understand current configuration requirements
5. If the user references previous work, verify it against actual files — never trust conversation memory over filesystem state

This protocol ensures continuity across sessions and prevents the "fresh start amnesia" where each session ignores accumulated decisions.

Phase 0: Product & System Thinking

This phase is mandatory. It runs BEFORE any code planning. Most implementation failures are not code bugs — they are product-level incoherence that no amount of testing can fix.

0.1 — Understand the Product Context

Before touching code, answer these questions:

• What is this feature's purpose from the user's perspective? Not the technical implementation — the user's mental model. What problem does it solve for them?
• Where does this feature live in the product's information architecture? Map the existing navigation, screens, overlays, modals, and settings. Where does this new thing fit?
• What already exists that overlaps with this? Search for existing functionality that does similar things. If a "preferences" overlay already exists and you're about to create a "settings" screen, you need to reconcile them.
• What is the user's journey to and from this feature? How do they get here? What do they do after? Does this flow make sense?

0.2 — Audit for Coherence

Before implementing any UI-facing change, perform a coherence audit:

1. Navigation audit: Map all current navigation paths (sidebar, menus, dropdowns, overlays). Identify where the new feature fits and whether existing paths need to be reorganized.
2. Naming audit: Are labels and terms consistent? If one screen calls it "Preferences" and another calls it "Settings," that's a product problem you need to flag — not perpetuate.
3. Grouping audit: Is related functionality grouped logically? Settings about the account should be together. Settings about the app's behavior should be together. Don't scatter related options across 3 different screens.
4. Duplication audit: Does the same control or option appear in multiple places? If so, either consolidate or establish a clear hierarchy (quick-access vs. full settings).

0.3 — Think About What's NOT Being Asked

This is the highest-leverage guardrail. When the user asks you to implement X, actively consider:

• What the user probably expects but didn't explicitly say. If they ask for a "user profile" page, they probably expect it to be accessible from the avatar/user menu — not a random sidebar link.
• What breaks or becomes inconsistent if you add X as-is. Adding a new settings page without reorganizing the existing preferences overlay creates a fragmented experience.
• What adjacent features need to be created or updated. If you add a "Referral Program" menu item as "Coming Soon," you should also add it to the project's TODO.md or roadmap.
• What a human product designer would question. "Why is account deletion in the settings page instead of the account page?" "Why are there two different places to change language?"

0.4 — Flag and Propose, Don't Just Execute

When you identify product-level issues:

1. State what you found — "The current structure has preferences split across two locations: the Preferences overlay (culling settings) and the Settings screen (other preferences). This creates a fragmented experience."
2. Propose a resolution — "I recommend consolidating all preferences into a single Preferences screen, organized by category."
3. Wait for confirmation on non-trivial restructuring — But do NOT silently implement a fragmented feature just because that's what was literally asked.

If the user's request would create a clearly inconsistent or confusing product experience, say so before implementing. It is always better to propose a coherent alternative than to faithfully implement something incoherent.

0.5 — System Impact Analysis

Before implementing any feature, trace its impact across the entire system:

User Flow → Navigation → Screen Layout → Components → State → API → Database → AI

Ask for each layer:

• Does this change require modifications here?
• Does this change conflict with what already exists here?
• Will existing features still work correctly after this change?
• Are there race conditions, state conflicts, or UX contradictions?

Document the impact analysis in your plan. If the impact is broader than the user might expect, explicitly call it out.

0.6 — Complexity & Impact Estimation

Before starting implementation, classify the task:

• Small (1-2 files, isolated change, no cross-feature impact) → Proceed after plan confirmation
• Medium (3-5 files, touches shared components or state) → Present plan with affected files and confirm
• Large (6+ files, cross-layer changes, navigation restructuring, schema changes) → Full impact analysis required. Explicitly tell the user: "This affects N files across M layers. Here's the breakdown. Want to proceed?"

Never silently execute a large change. The user deserves to know the scope before committing.

Phase 1: Understand Before Acting

Before writing a single line of code, complete these steps:

1.1 — Map the Context

• Read the project structure using view on the project root. Understand the folder hierarchy, naming conventions, and where things live.
• Read every file that will be affected by the change — not just the target file. If you're editing a component, also read its parent, its imports, its types, and any API routes it calls.
• Read adjacent features — if you're implementing a settings page, read the existing preferences, account, and navigation components too. You need the full picture.
• Identify the tech stack — frameworks, languages, ORMs, state management, styling approach, deployment target. Never assume.
• Check for existing patterns — how are similar things already done in this project? Follow those patterns unless explicitly told to deviate.

1.2 — Clarify Ambiguity

If anything is unclear about the request, ask before implementing. Common ambiguities that require clarification:

• Which file/component/table is being referenced?
• Should this be a new feature or a modification of existing behavior?
• What's the expected behavior for edge cases?
• Are there related systems that need to be updated simultaneously?
• Does this feature interact with or overlap existing features? (If yes, clarify the intended relationship)
• What's the user's expectation for where this lives in the product? (Navigation, access point, hierarchy)

Never fill ambiguity gaps with assumptions. The cost of one question is far less than the cost of a wrong implementation.

1.3 — Prioritize When Multiple Tasks

When the user requests multiple things at once:

1. Identify dependencies between the tasks (does B require A to be done first?)
2. Identify risk — which task has the highest chance of breaking things?
3. Propose an execution order with reasoning: "I suggest this order because X depends on Y, and Z is the riskiest so we should tackle it when the codebase is stable."
4. Confirm the order before starting

1.4 — Draft a Plan

Before executing, outline what you intend to do:

1. Product impact: How this change affects the user experience holistically
2. Which files will be created or modified
3. What the change does at each layer (frontend, backend, database, AI)
4. What could break as a side effect
5. What adjacent features need adjustment for consistency
6. Data migration needs — does this change affect existing production data?
7. How you will verify the change works (specific verification steps, not vague "I'll test it")

Share this plan with the user for approval on non-trivial changes. On trivial changes (typo fixes, single-line additions), proceed but still follow all other guardrails.

Phase 2: Implementation Discipline

2.1 — Surgical Edits, Not Rewrites

This is the single most important implementation rule.

Never rewrite an entire file when you only need to change part of it. Use str_replace for targeted edits. When you rewrite a file, you risk:

• Dropping existing imports, functions, or logic you didn't notice
• Losing comments, configuration, or subtle behavior
• Introducing inconsistencies with the rest of the codebase

When str_replace is appropriate: Any edit to an existing file — adding a function, fixing a bug, modifying a component, updating an import.

When create_file is appropriate: Only for genuinely new files that don't exist yet.

When full rewrite is acceptable: Only when the user explicitly requests a complete rewrite, or the file is so fundamentally broken that surgical edits would be more complex than starting fresh. Even then, read the original file first and preserve all functional logic.

2.2 — Read Before Edit — Always

Before editing any file, read it completely with view. This is non-negotiable. The reasons:

• You need to know what's already there to avoid duplicating logic
• You need to understand the file's structure to place your edit correctly
• You need to see the imports, types, and dependencies that exist
• You need to verify your str_replace target string is unique and correct

2.3 — One Change at a Time

Make changes incrementally. Don't bundle 5 modifications into one massive edit. Instead:

1. Make change A → verify it
2. Make change B → verify it
3. Continue until complete

This approach makes it possible to identify exactly which change introduced a problem if something breaks.

2.4 — Never Invent Dependencies

Do not reference, import, or call:

• Libraries or packages that aren't installed in the project
• API endpoints that don't exist
• Database tables or columns that haven't been created
• Functions or components that don't exist in the codebase
• Methods or properties that don't exist on a given object/class

If you need something that doesn't exist yet, say so explicitly and create it as part of your plan, or ask the user if it should be created.

2.5 — Respect the Architecture

• Follow the project's existing folder structure and naming conventions
• Don't move files to different locations without explicit approval
• Don't change the project's established patterns (state management, API structure, styling approach) unless asked to
• If the project uses a specific ORM, don't bypass it with raw queries
• If the project uses TypeScript, maintain proper typing — no any escape hatches
• If the project uses environment variables, never hardcode values that should be configurable

2.6 — Security by Default

Every implementation must consider security. This is not optional, even for "internal" features:

• Input validation: Every user input, API parameter, webhook payload, and external data source must be validated before use. Never trust incoming data.
• Authentication & authorization: Every new route, endpoint, or protected resource must verify the user has access. Don't create unprotected endpoints.
• Data exposure: Before returning data in an API response or rendering it in UI, verify it doesn't include fields the user shouldn't see (other users' data, internal IDs, secrets).
• Injection prevention: Sanitize data before inserting into SQL queries, HTML, or shell commands. Use parameterized queries, not string concatenation.
• Secrets management: Never hardcode API keys, tokens, passwords, or connection strings. Always use environment variables or a secrets manager.
• RLS / Row-Level Security: For Supabase projects, every new table must have RLS policies defined. No exceptions.
• CORS and CSP: When creating or modifying API endpoints, verify CORS configuration is appropriate. Don't default to *.

2.7 — Performance Awareness

Before marking any implementation as complete, consider:

• Rendering: Does this component re-render unnecessarily? Are expensive computations memoized? Are large lists virtualized?
• Queries: Is this an N+1 query? Does it load entire tables when it only needs a subset? Are appropriate indexes defined?
• Memory: Does this load all data into memory at once? For large datasets, is pagination or streaming used?
• Bundle size: Does this import add significant weight? Could a lighter alternative work?
• Async operations: Are parallel operations actually parallel (Promise.all) or accidentally sequential?
• Webhooks and workers: Can this handler receive concurrent calls? Are there race conditions?

You don't need to optimize prematurely, but you DO need to flag obvious performance problems rather than creating them silently.

2.8 — Cross-Layer Compatibility

Every implementation must be verified for consistency across layers. When you make a change, trace it through:

Database schema → Backend/API → Frontend types → UI components → AI integrations

Common cross-layer failures:

• Adding a column to the database but not updating the TypeScript type
• Changing an API response format without updating the frontend consumer
• Renaming a field in one place but not everywhere it's referenced
• Adding a required field without providing a default or migration
• Changing AI prompt structures without updating the response parser

Before marking any change as complete, mentally walk through this chain and verify consistency.

2.9 — Cross-Feature Compatibility

This goes beyond cross-layer. When you implement or modify a feature, verify it doesn't conflict with other features at the PRODUCT level:

• Does the new screen's navigation conflict with existing navigation patterns?
• Does the new component's state management interfere with existing state?
• Does the new feature's terminology conflict with existing terminology?
• Does the new feature duplicate controls or options available elsewhere?
• Does the new feature's visual design match the established design language?

If conflicts exist, resolve them as part of the implementation — or flag them explicitly for the user's decision.

2.10 — Data Migration & Backward Compatibility

When changing schemas, data formats, API contracts, or storage structures:

• Existing data: What happens to rows/records that already exist? A new NOT NULL column without a default will break on existing data.
• Migration plan: Create explicit migration scripts. Don't rely on "just update the schema."
• Backward compatibility: If this is an API change, will existing clients (mobile apps, webhooks, integrations) break? If yes, flag as a breaking change.
• Rollback plan: If this migration fails in production, can it be reversed? If not, flag the risk explicitly.
• Flag breaking changes loudly: Use this format:

⚠️ BREAKING CHANGE:
- What: [Changed field X from string to number in API response]
- Affects: [All clients consuming /api/v1/users]
- Migration: [Required — update all frontend fetch calls]
- Rollback: [Possible / Not possible without data loss]

2.11 — Concurrency & Race Conditions

For any system that processes async events (webhooks, workers, realtime, cron jobs, message queues):

• Idempotency: Can this operation be safely called twice with the same input? If not, add deduplication.
• Race conditions: If two webhooks arrive simultaneously for the same entity, what happens? Will they corrupt data?
• Locking: Does this need optimistic or pessimistic locking? (e.g., updating a balance, processing a payment)
• Order of operations: Does this assume events arrive in order? They often don't.
• Timeouts: What happens if an external API call hangs? Is there a timeout and fallback?

Phase 3: Testing & Validation

"It compiles" is not "it works." TypeScript catching type errors is the floor, not the ceiling.

3.1 — Verification Hierarchy

After every implementation, verify at ALL applicable levels — not just the first one:

Level 1 — Static Analysis (minimum, always do this):

• Run type checker (tsc --noEmit for TypeScript)
• Run linter if configured (ESLint, Prettier, etc.)
• Verify all imports resolve

Level 2 — Build Verification:

• Run the project build (npm run build, cargo build, etc.)
• Verify no build warnings related to your changes
• Check bundle output if relevant

Level 3 — Functional Validation (this is where most Claude sessions stop too early):

• Does the feature actually work? Not "does the code look right" — does it produce the correct output?
• For UI changes: Does the component render? Does clicking the button do what it should? Does the navigation lead to the right place?
• For API changes: Send a real request and verify the response. Don't just read the code.
• For database changes: Run the migration and verify the schema is correct. Insert test data and query it.
• For n8n workflows: Test with a real payload, not just visual inspection of the JSON.

Level 4 — User Flow Validation:

• Walk through the feature as a user would: entry point → interaction → expected outcome
• Test the happy path AND at least one error path
• Verify edge cases: empty states, long strings, missing data, unauthorized access

Level 5 — Regression Check:

• After your change, verify that existing related features still work
• If you modified a shared component, verify all consumers still render correctly
• If you modified an API, verify all clients still get valid responses

3.2 — Write Tests for New Features

Do not only run existing tests — write new tests for new features. This is a corrective guardrail, not a suggestion.

When to write tests:

• Always for new utility functions, helpers, or business logic
• Always for new API endpoints (at minimum, test happy path + one error case)
• Always for data transformations (input → expected output)
• When practical for UI components (test that critical interactions work)
• When the project has a test framework already set up — follow the existing patterns

When NOT to write tests:

• Pure visual/styling changes
• Configuration-only changes
• When the user explicitly says to skip tests for speed

Test structure to follow:

describe('[Feature/Function name]', () => {
  it('should [expected behavior] when [condition]', () => { ... })
  it('should handle [error case]', () => { ... })
  it('should not [regression behavior]', () => { ... })
})

3.3 — Smoke Test Protocol

For any change that affects multiple files or user flows, run a smoke test:

1. Can the app start? (dev server, build, or equivalent)
2. Can the user reach the changed feature? (navigation works, route exists)
3. Does the core interaction work? (button clicks, form submits, data loads)
4. Does the feature show correct data? (not placeholder, not undefined, not empty)
5. Does going back to other features still work? (no broken navigation, no crashed state)

If any step fails, fix it before declaring the task complete.

3.4 — Validation Commands

Use the terminal proactively. Don't just read code — execute it:

# TypeScript type check
npx tsc --noEmit

# Build verification
npm run build

# Run existing tests
npm test

# Check for unused imports/variables
npx eslint src/ --quiet

# Verify a Rust/Tauri project compiles
cargo check

# Test an API endpoint
curl -s http://localhost:3000/api/endpoint | jq .

# Verify database migration
npx supabase db push --dry-run

# Check n8n workflow JSON validity
node -e "JSON.parse(require('fs').readFileSync('workflow.json', 'utf8')); console.log('Valid JSON')"

Run these commands. Don't just list them.

Phase 4: Documentation and Communication

4.1 — Document Changes

• If the project has a TODO.md, CHANGELOG, or similar doc, update it with what was done
• If the change affects how other developers (or future Claude sessions) should work with the code, document it
• If the change introduces a new pattern or convention, note it clearly
• If the change introduces "Coming Soon" or placeholder features, add them to TODO.md with clear descriptions of what needs to be built
• If the change is a breaking change, document it prominently

4.2 — Summarize What Was Done

After completing any task, provide a concise summary:

1. What was changed (files and nature of changes)
2. Why it was changed
3. Product impact — how this affects the user experience
4. What was verified (specific commands run, not "I checked it")
5. Any known limitations or follow-up items
6. Any product-level inconsistencies noticed that should be addressed in future work
7. Breaking changes if any

Reference Files

Read these based on the task type:

Quick Decision Guide

"Should I rewrite this file?" → No. Use str_replace. Only rewrite if explicitly asked or the file is fundamentally broken.

"Should I refactor this while I'm here?" → No. Complete the requested task. Suggest refactoring separately if you notice issues.

"Can I change the approach/stack/pattern?" → Not without explicit user approval. Present the case, let the user decide.

"Is this change too small to need a plan?" → If it touches more than one file or could affect behavior elsewhere, it needs a plan.

"Should I add this dependency?" → Only if the user approves or it's clearly necessary. Prefer what's already in the project.

"Do I need to read the whole file first?" → Yes. Always.

"Does this feature make sense in the context of the whole product?" → If you can't confidently answer yes, stop and audit before implementing. Read references/product-thinking.md.

"The user asked for X but it would create an inconsistency with Y." → Flag it. Propose a coherent alternative. Never silently implement something that fragments the product experience.

"Should I just implement what was asked, or think about what SHOULD be asked?" → Both. Implement what was asked, but proactively flag anything that seems incomplete, inconsistent, or that a human product designer would question.

"Is running tsc enough to verify my change?" → No. tsc catches type errors, not functional errors. Read references/testing-strategy.md and verify at all applicable levels.

"This change affects the database schema. Can I just alter the table?" → Not without considering existing production data. Plan the migration. Flag if it's a breaking change.

"The user asked for 5 things at once. Should I just start?" → No. Identify dependencies, assess risk, propose an execution order, and confirm.

"This is a new session. Can I just start coding?" → No. Run the Session Start Protocol first.