Deterministic AI Workflows: Engineering File-Based Configurations for Cursor and Claude Code

Current Situation Analysis

Modern AI coding assistants are frequently deployed as conversational co-pilots rather than deterministic engineering tools. Developers paste system prompts at the start of a session, manually coach the model through repetitive patterns, and accept inconsistent output as a baseline cost. The fundamental issue is architectural: prompts are ephemeral. They live in chat history, degrade across context windows, and lack enforcement mechanisms. When an AI generates a placeholder test, an ambiguous code review, or a blocking database migration, the failure isn't a model limitation—it's a configuration gap.

This problem is routinely overlooked because teams treat AI assistance as a soft skill rather than a pipeline component. In reality, reliable AI behavior requires structural constraints that operate outside the conversation layer. Production-grade setups don't rely on remembering to say "review this carefully" or "write production-ready tests." They encode those expectations into the toolchain itself.

Empirical iteration reveals a consistent pattern: each reliable AI behavior requires 30–60 minutes of constraint encoding. Without explicit boundaries, models default to safe, vague, or incomplete outputs. Security findings lack standardized references. Migrations omit rollback scripts. Long-running tasks lose state on session interruption. The solution isn't better prompting—it's file-based configuration that modifies how the assistant routes requests, enforces boundaries, and maintains operational state.

WOW Moment: Key Findings

Shifting from conversational prompting to structured configuration transforms AI from a reactive assistant into a deterministic pipeline. The following comparison illustrates the operational impact of adopting file-based constraints versus ad-hoc instruction:

Approach	Output Consistency	Automation Coverage	Failure Recovery	Maintenance Overhead
Ad-Hoc Prompting	Variable (degrades across sessions)	Manual coaching required	Session-dependent, stateless	High (re-explaining patterns)
File-Based Configuration	Deterministic (enforced at toolchain level)	Auto-delegation + lifecycle hooks	Checkpoint-resilient, state-aware	Low (drop-in deployment)

This finding matters because it decouples AI reliability from human memory. When constraints are encoded in agents, hooks, and skills, the assistant behaves predictably across projects, teams, and context windows. You stop coaching the model and start configuring the environment. The result is a setup that enforces standards, blocks unsafe operations, and maintains execution state without manual intervention.

Core Solution

The architecture rests on three primitives that align with how Cursor and Claude Code parse and execute configurations: subagents for domain-specific delegation, lifecycle hooks for boundary enforcement, and skills for protocol encoding. Each primitive operates independently but composes into a deterministic workflow.

1. Subagent Configuration: Domain-Specific Delegation

Subagents live in .claude/agents/ as Markdown files with YAML frontmatter. The description field controls auto-routing, while the system prompt enforces output structure and constraints. Instead of vague instructions, the prompt defines explicit categories, mandatory references, and decision gates.

Example: security-auditor.md

---
model: claude-sonnet-4-20250514
description: "Analyze code for security vulnerabilities, data integrity risks, and performance bottlenecks. Returns structured findings with severity ratings and deployment verdict."
---
You are a security and reliability auditor. Evaluate the provided code against the following categories:
1. Correctness defects (logic errors, edge cases)
2. Security vulnerabilities (must reference OWASP Top 10 or explicitly state "not mapped" with justification)
3. Data integrity risks (loss, corruption, race conditions)
4. Performance constraints (N+1 queries, unbounded loops, memory leaks)

Output format:
- Severity table (Critical/High/Medium/Low)
- Actionable remediation steps
- Final verdict: APPROVE, REVISION_REQUIRED, or BLOCK_DEPLOYMENT

Constraints:
- Never omit OWASP mapping for security findings
- Never output ambiguous verdicts
- Include specific line references for each finding

Why this works: The description triggers auto-delegation when the user requests a review. The system prompt replaces conversational coaching with structural constraints. The mandatory OWASP reference prevents vague security notes. The explicit verdict gate forces a decision rather than leaving the call to the developer.

2. Lifecycle Hooks: Boundary Enforcement

Hooks execute shell scripts at specific points in the toolchain lifecycle. A PreToolUse hook fires before Edit, Write, or MultiEdit operations. Exiting with code 2 blocks the operation and surfaces the hook output to the model, forcing correction before retry.

Example: enforce-standards.sh

#!/usr/bin/env bash
set -euo pipefail

TARGET_FILE="$1"
EXT="${TARGET_FILE##*.}"

# Graceful degradation: skip if linter is absent
run_linter() {
  local tool="$1"
  local args="$2"
  if command -v "$tool" &>/dev/null; then
    eval "$tool $args"
    return $?
  fi
  return 0
}

case "$EXT" in
  ts|tsx|js|jsx)
    OUTPUT=$(run_linter "npx" "eslint --format json $TARGET_FILE 2>&1") || true
    ;;
  py)
    OUTPUT=$(run_linter "ruff" "check $TARGET_FILE --output-format json 2>&1") || true
    ;;
  rs)
    OUTPUT=$(run_linter "cargo" "clippy --message-format json 2>&1") || true
    ;;
  *)
    exit 0
    ;;
esac

if echo "$OUTPUT" | grep -q '"error_count":[1-9]'; then
  echo "[HOOK] Lint violations detected. Fix before proceeding."
  echo "$OUTPUT"
  exit 2
fi

exit 0

Why this works: The script validates tool availability before execution, preventing false blocks when linters aren't installed. Exit code 2 enforces a hard boundary without breaking the workflow. The model receives the exact error output and self-corrects. A complementary post-edit-test hook can run after modifications to validate behavior without blocking, using exit 0 for informational feedback.

3. Skills: Protocol Encoding

Skills reside in .claude/skills/ and contain a SKILL.md that defines operational protocols. Unlike instructions, skills encode state management, resilience patterns, and production-grade behaviors that persist across sessions.

Example: .claude/skills/resilient-integration/SKILL.md

# Resilient API Integration Protocol

When implementing external service integrations, enforce the following constraints:

1. Credential Management
   - Never hardcode secrets
   - Resolve via environment variables or secret managers
   - Fail fast on missing credentials

2. Network Resilience
   - Set explicit connection and read timeouts
   - Implement exponential backoff with jitter (base: 1s, max: 30s, jitter: ±20%)
   - Parse and respect Retry-After headers

3. Idempotency & State
   - Attach idempotency keys to all POST/PUT requests
   - Implement circuit breaker pattern (failure threshold: 5, recovery timeout: 60s)
   - Log request/response pairs for audit trails

4. Verification
   - Validate webhook signatures using HMAC-SHA256
   - Reject unverified payloads immediately

Why this works: Skills operate as behavioral contracts. When the assistant auto-delegates to a skill, it inherits the protocol rather than guessing implementation details. This eliminates inconsistent error handling, missing timeouts, and hardcoded secrets across generated integrations.

Pitfall Guide

1. Ambiguous Agent Descriptions

Explanation: Vague descriptions cause incorrect auto-delegation. The model routes requests to the wrong agent, producing irrelevant or shallow output. Fix: Use action-oriented, domain-specific descriptions. Include trigger keywords and expected output types. Test routing with sample prompts before deployment.

2. Hook Exit Code Mismanagement

Explanation: Using exit 2 for informational messages or missing tools blocks valid edits unnecessarily. Conversely, using exit 0 for hard violations allows unsafe code to pass. Fix: Reserve exit 2 for policy violations only. Use exit 0 for graceful skips, missing tools, or informational logs. Document exit code semantics in hook scripts.

3. Ignoring Database Lock Semantics

Explanation: Generating ADD COLUMN NOT NULL with a default value on large tables causes full table locks in older PostgreSQL versions, blocking writes during migration. Fix: Encode a three-step pattern: add nullable column → backfill in batches → apply constraint. Generate independent rollback scripts for each step. Validate lock impact before execution.

4. Placeholder Test Generation

Explanation: Models default to // TODO or pass statements when test structure is unclear, producing non-runnable scaffolding. Fix: Explicitly ban placeholder statements in system prompts. Require runnable assertions, framework detection, and coverage of edge cases. Validate generated tests against the project's test runner.

5. State Loss in Long Tasks

Explanation: Multi-step operations lose progress on session interruption or context overflow, forcing manual restarts. Fix: Implement checkpoint files (_state.json) that track step indices, completion status, and intermediate outputs. Design skills to read state on initialization and resume from the last completed step.

6. Hardcoded Credentials in AI Output

Explanation: Models embed API keys or database passwords directly in generated code when not constrained. Fix: Enforce environment variable resolution in skill protocols. Add pre-commit hooks that scan for secret patterns. Require credential lookup functions in integration templates.

7. Hook Script Path Fragility

Explanation: Relative paths or missing executable permissions cause hooks to fail silently or throw permission errors. Fix: Use absolute or project-root relative paths. Set executable permissions (chmod +x). Validate script existence in settings configuration. Log hook execution status for debugging.

Production Bundle

Action Checklist

• Audit existing prompts: Identify repetitive instructions that should be encoded as constraints
• Create agent directory: Initialize .claude/agents/ and define YAML frontmatter for each subagent
• Draft hook scripts: Write lifecycle scripts with explicit exit code semantics and tool availability checks
• Configure settings merge: Add hook definitions to .claude/settings.json with correct event triggers
• Build skill protocols: Define operational contracts in .claude/skills/ with state management and resilience patterns
• Test routing: Verify auto-delegation by triggering agents with sample prompts and validating output structure
• Validate hooks: Run edits that trigger lint/test hooks and confirm blocking/informing behavior matches expectations
• Document constraints: Maintain a CONFIGURATION.md explaining each file's purpose, exit codes, and failure modes

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Domain-specific analysis (security, performance, testing)	Subagents	Auto-delegation based on description reduces manual routing	Low (one-time setup)
Enforcing standards before file writes	PreToolUse hooks	Blocks invalid operations at the toolchain level	Medium (requires script maintenance)
Long-running or multi-step operations	Skills with checkpointing	Preserves state across sessions and interruptions	Low (protocol definition)
Post-modification validation	PostToolUse hooks	Provides feedback without blocking workflow	Low (informational only)
Cross-project consistency	Shared skill/agent templates	Standardizes behavior across repositories	Medium (initial template engineering)

Configuration Template

.claude/settings.json (Hook Registration)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "command": "bash .claude/hooks/enforce-standards.sh {{tool_input.file}}"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "command": "bash .claude/hooks/run-affected-tests.sh {{tool_input.file}}"
      }
    ]
  }
}

.claude/agents/schema-migrator.md (Safe Migration Agent)

---
model: claude-sonnet-4-20250514
description: "Generate safe database migrations with lock-aware SQL, batch backfill logic, and independent rollback scripts."
---
You are a database migration engineer. Analyze schema changes for lock impact and generate safe SQL sequences.

Rules:
- Detect table size estimates and PostgreSQL version constraints
- Convert ADD COLUMN NOT NULL into three steps: nullable add → batch backfill → constraint apply
- Generate independent down blocks for each step
- Include transaction boundaries and batch size recommendations
- Flag operations that require maintenance windows

Output format:
- Up migration SQL
- Down migration SQL
- Lock impact analysis
- Execution recommendations

Quick Start Guide

1. Initialize directories: Create .claude/agents/, .claude/skills/, and .claude/hooks/ in your project root.
2. Drop in configurations: Copy agent Markdown files, skill directories, and hook scripts into their respective folders. Set executable permissions on shell scripts.
3. Merge settings: Add hook definitions to .claude/settings.json using the provided template. Validate JSON syntax before saving.
4. Validate routing: Trigger agents with sample prompts. Confirm auto-delegation matches descriptions and output adheres to constraints.
5. Test boundaries: Perform edits that trigger lint/test hooks. Verify exit code behavior matches expectations (block on violation, inform on success).

This configuration shifts AI assistance from conversational coaching to deterministic execution. By encoding constraints at the toolchain level, you eliminate repetitive instruction, enforce production standards, and maintain operational state across sessions. The result is a setup that behaves like a senior engineering partner without requiring manual calibration per project.