tools-only Advanced Workflow Patterns
Validation Scripts and Error Handling
For fragile operations, create validation scripts that catch errors early.
Example: PDF Form Filling with Validation
## PDF form filling workflow
1. Extract form structure: `python scripts/extract_fields.py input.pdf fields.json`
2. **Validate field mappings**: `python scripts/validate_boxes.py fields.json`
- Returns: "OK" or lists conflicts
3. Apply values: `python scripts/fill_form.py input.pdf fields.json output.pdf`
Why Validation Scripts Work
- Machine-verifiable checks
- Specific error messages: "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"
- Early error detection before destructive changes
- Clear debugging paths
Script Best Practices
- Make scripts solve problems rather than punt to Claude
- Include explicit, helpful error handling
- Avoid "voodoo constants" - justify all hardcoded values
- Document what each script does and when to use it
Create Verifiable Intermediate Outputs
The "plan-validate-execute" pattern catches errors early by having Claude create a plan in structured format, validate with a script, then execute.
Problem Example
User asks Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might:
- Reference non-existent fields
- Create conflicting values
- Miss required fields
- Apply updates incorrectly
Solution: Plan-Validate-Execute
Workflow becomes: analyze → create plan file → validate plan → execute → verify
Add intermediate changes.json file validated before applying changes.
Why This Pattern Works
- Catches errors early: Validation finds problems before changes applied
- Machine-verifiable: Scripts provide objective verification
- Reversible planning: Claude can iterate on plan without touching originals
- Clear debugging: Error messages point to specific problems
When to Use
Batch operations, destructive changes, complex validation rules, high-stakes operations.
Use Visual Analysis
When inputs can be rendered as images, have Claude analyze them:
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
Claude's vision capabilities help understand layouts and structures difficult to describe programmatically.
Workflow Pattern Examples
Sequential Workflow (Low Ambiguity)
## Deploy application
1. Run tests: `npm test`
2. Build production: `npm run build`
3. Deploy: `python scripts/deploy.py --environment prod`
4. Verify deployment: Check output for "Deployment successful"
Conditional Workflow (Medium Ambiguity)
## Process customer data
1. Validate input format
2. If CSV format:
- Use pandas for processing
3. If JSON format:
- Use json module for processing
4. Transform according to schema in `references/schema.md`
5. Output to database
Open-Ended Workflow (High Ambiguity)
## Analyze codebase
1. Identify the primary language and frameworks
2. Review architecture and organization
3. Check for common issues:
- Security vulnerabilities
- Performance bottlenecks
- Code quality concerns
4. Generate report with findings and recommendations
XML Tags for Structure
Claude was trained with XML tags in training data. Use them to structure complex skills:
<workflow>
1. <step>Validate input</step>
2. <step>Process data</step>
3. <step>Generate output</step>
</workflow>
<examples>
<example type="simple">...</example>
<example type="complex">...</example>
</examples>
Especially useful for:
- Complex multi-step workflows
- Organizing multiple examples
- Structuring reference material
- Separating instructions from metadata