Read-First Priority: Perform Read-Only Validation Before Running on the Target System for the First Time

Specific Scenarios

You are deploying configuration changes to a new environment, or having an AI modify production configurations within a thread. You write a change, push it, and the entire service crashes, with colleagues complaining about you. Classic scenarios include:

1. You write a configuration change, push it, and the service crashes.

2. You modify an API in a thread, and QA discovers that it altered the return values of three other APIs.

3. You perform environment probing in production, resulting in corrupted health check status flags.

The problem isn't your technical skill; it's that you skipped a step. **Perform read-only validation first.**

What is Read-Only Validation?

**Read-Only Validation = Run through the target system in read-only mode before completing the change.** This means you do not modify anything; you only check what side effects your changes might encounter at various levels.

A read-only validation consists of three sub-steps:

| Sub-step | Question to Answer | Typical Operations |

|--------|----------------|----------|

| Dependency Check | Which modules will my change touch? Which ones are read-only? | Static analysis / Lint / Documentation search |

| Impact Assessment | Will other code at the same layer be affected? | Thread tracing / Traffic tracing / Log search |

| State Confirmation | Is the data I'm seeing the current state? Could it be modified concurrently? | CHECKSUM / Timestamp / Status flag comparison |

When to Use It

- **Making the first change in a new environment**

- **Changes involving shared resources** (APIs, databases, configurations)

- **You don't know the full architecture** and can only see part of it

- **Risk of concurrent modifications** (multiple people editing simultaneously, or scheduled tasks running)

- **You are having an AI or automated system modify code**, and you cannot manually review all changes

When You Can Skip It

- You clearly understand the architecture, and the scope of the change is pinpointed

- You have made this type of change many times before (it’s not the first time)

- There are practical automated regression tests as a safety net

- The change does not involve shared state (e.g., editing your own documentation)

How to Do It (3 Steps)

Step 1: Dependency Graph Boundary Check

You may have performed dependency梳理 (sorting/mapping) many times, but often miss one category during the process: read-only judgment.

**Correct Approach:**

1. List all modules to be changed.

2. For each module, identify all locations that might read data from it.

3. For each read location, confirm whether it is strictly read-only or if it modifies state while reading.

4. Mark non-read-only locations.

# Example: Modifying config.yaml
-grep -r "config.yaml" --include "*.py"
# Found:
#   main.py:5  read_config()       # Read-only → Safe
#   cache.py:12 load_config()      # Read-only → Safe
#   health.py:8 check_config()     # Reads then updates status flag → Non-read-only → Marked

Step 2: Impact Scope Tracing

This step is the most tedious but also the most valuable. You need to answer: **Will other code in the same version be affected?**

**Specific Operations:**

1. Identify all callers of the same API endpoint.

2. For each caller, confirm whether its handling of the return value is read-only.

3. For database-related changes, find all locations reading that table and confirm whether they perform write operations while reading.

4. For shared state, find all locations reading that state and confirm if there are concurrent modifications.

**Checklist:**

- [ ] Which API endpoints return data from this module?

- [ ] Which code directly reads fields from this table?

- [ ] Which modules share this status flag/cache key?

- [ ] Are there scheduled tasks or webhooks that will modify the state I am touching?

Step 3: State Confirmation (CHECKSUM Comparison)

This step ensures that the data you are seeing hasn't already been changed by someone else.

**Specific Operations:**

1. Before starting your check, fingerprint the key data.

2. During the check, if you encounter a non-read-only operation, stop and re-fingerprint.

3. Finally, compare fingerprints to confirm the data was not tampered with during intermediate steps.

# Method 1: Direct file fingerprint
md5sum config.yaml > /tmp/config-before.md5
# ... your checks and jitter ...
md5sum config.yaml > /tmp/config-after.md5
diff /tmp/config-before.md5 /tmp/config-after.md5

# Method 2: Timestamp comparison
stat -c "%Y %n" config.yaml  # Linux
stat -f "%m %N" config.yaml  # macOS

Common Pitfalls

1. **Only performing static checks, not dynamic tracing** — Static analysis only sees what is written in the code, not what is actually triggered at runtime.

2. **Missing async/webhooks/scheduled tasks** — These are not on the main call chain and are easiest to overlook.

3. **Incorrect timing for fingerprinting** — You take fingerprints during the check, but the data appears to be from after the check, meaning you missed an intermediate modification.

4. **Confusing "read-only" with "not modifying files"** — Reading may modify cache, health bits, or session states. This isn't "modifying a file," but it is indeed a non-read-only operation.

5. **Using read-only validation as a substitute for regression testing** — Read-only validation confirms your timing for inspection is correct, but it does not confirm your changes are correct. Neither can be skipped.

Minimal Viable Checklist

**Before Starting the Check:**

- [ ] List all modules I will touch

- [ ] Determine read-only/non-read-only status for each read location

- [ ] Identify upstream callers at the same level

- [ ] Confirm if any scheduled tasks/webhooks touch the data I care about

- [ ] Take data fingerprints

**During the Check:**

- [ ] Stop every time a non-read-only operation is discovered

- [ ] Re-take fingerprints to confirm the timeline

**After Completing the Check:**

- [ ] Fingerprints match consistently

- [ ] All non-read-only locations are marked

- [ ] Your judgment aligns with the observed architecture, with no omissions

Relationship Between Post-Check and Development Process

Read-only validation is the first gate before development planning. It doesn't tell you if your change is correct; it only tells you **whether your understanding aligns with your target system**.

This is why it is important: In the paradigm of AI-generated code, your knowledge of the architecture shifts from "what you remember" to "what you have verified." Read-only validation is the checklist for "what you have verified."