Write instructions that actually work with Claude Code and AI assistants

I love Claude's MCP functions - searching files, saving data, writing to SQL. But writing complex logic in claude.md files? Pain.

JavaScript is easy for simple tasks, but for complex workflows with loops and conditionals, I needed something between human text and actual code. Plain English wasn't precise enough - Claude would skip files, apply conditions wrong, get confused about data structures.

So I discovered some programming-language-like syntax patterns that bridge the gap. Claude understands exactly what I mean without full JavaScript.

The Core Issue

Human documentation: "Process files based on priority and handle errors appropriately"

What Claude Code needs:

FOR each .json file in /data:
  IF file.priority >= 5 AND file.status === "active":
    result = process(file)
    IF result.success: save to /output
    ELSE: log error, continue

Tip 1: Write Executable Pseudocode

❌ Vague:

markdown

Loop through data and apply business rules

✅ Explicit:

markdown

FOR each item in data.items:
  IF item.status === "active" AND item.priority > threshold:
    process_item(item)
  ELSE IF item.status === "inactive":
    archive_item(item)  
  ELSE:
    skip_item(item)

Claude Code can translate this directly into working code.

For complex, dynamic logic with loops and conditions, here are some effective ways to describe it clearly in your claude.md:

1. Pseudocode blocks

Best for: Sequential logic with clear step-by-step flow

## Main Logic Flow

FOR each file in directory:
    IF file is JSON:
        data = parse(file)
        FOR each item in data:
            IF item meets condition X:
                process_item(item)
            IF result.status == "success":
                save_to_output(result)
            ELSE:
                log_error(item.id)

2. Flowchart in text

Best for: Visual thinkers who need to see process branches

## Process Flow
Start → Scan directory for files
  ↓
Filter JSON files → For each JSON file:
  ↓
Parse file data → For each data item:
  ↓
Check condition → IF condition met:
  ↓              ↓
Process item    Skip item
  ↓
Save result OR Log error

3. Nested structure with variables

Best for: Complex workflows with dynamic configuration

## Dynamic Logic Structure

### Variables (dynamic):
- `input_directory`: Can be any folder path
- `condition_rules`: JSON object with filtering criteria  
- `output_format`: Determines how results are saved

### Processing Logic:
1. **File Discovery**
   - Scan `{input_directory}` recursively
   - Filter for `*.json` files only

2. **Per-File Processing**
    FOR file in json_files:
        data = load_json(file)

    results = []

     FOR item in data:
       IF evaluate_condition(item, condition_rules):
         result = process_item(item)
         results.append(result)

3. **Conditional Output**
- IF results not empty: save_output(results, output_format)
- ELSE: log("No items matched criteria in {file}")

4. Decision tree format

Best for: Multiple branching conditions with different outcomes

## Logic Decision Tree

**For each file:**
- Is it JSON? 
  - NO → Skip file
  - YES → Continue to data processing

**For each data item in JSON:**
- Does item.status == "active"?
  - NO → Skip item  
  - YES → Check next condition
    - Is item.priority > threshold?
      - NO → Add to low_priority_queue
      - YES → Process immediately
        - Processing successful?
          - YES → Save result
          - NO → Add to retry_queue

5.Decision Tables for Complex Conditions

Best for: Multiple conditions that interact in complex ways

## Processing Rules Decision Table

When you have multiple conditions, tables eliminate ambiguity:

| status   | priority | category | file_size | action          | output_location    |
|----------|----------|----------|-----------|-----------------|-------------------|
| active   | >= 5     | A        | < 10MB    | process_high    | /output/high/     |
| active   | >= 5     | B,C      | < 10MB    | process_medium  | /output/medium/   |
| active   | >= 5     | any      | >= 10MB   | process_batch   | /batch/           |
| active   | < 5      | any      | any       | queue_later     | /queue/           |
| inactive | any      | any      | any       | archive         | /archive/         |
| pending  | any      | any      | any       | skip            | none              |

### Implementation:
Check conditions from top to bottom, first match wins.

FOR each item:
  FOR each rule in decision_table:
    IF item matches ALL conditions in rule:
      execute rule.action
      BREAK to next item

When to Use Which Method

Choose pseudocode blocks for sequential logic with simple loops and linear flow.

Go with flowchart in text when you have multiple decision points and visual representation helps clarify branches.

Use nested structure with variables for workflows with configurable parameters that change based on runtime settings.

Pick decision tree format for 2-4 levels of nested conditions where binary choices dominate your logic.

Choose decision tables when you have 3+ interacting conditions, need explicit handling of all combinations, or want to avoid deeply nested IF statements. For complex workflows, mix and match these methods - start with a flowchart for overall structure, then use decision tables for detailed rule sections and pseudocode for sequential processing steps.

Tips & Tricks Claude.md : Making AI Understand Your Loops & Conditionals