vm-cloudflare/AGENT_GUARDRAILS.md

AGENT GUARDRAILS for CLOUDFLARE Project

Purpose: Prevent common coding mistakes when using autonomous agents (Cline, Claude, etc.)

Governed by: RED-BOOK.md — See Appendix A for agent constraints

Copy this into your agent prompt before asking for code changes.

---

🛡️ CRITICAL RULES

1. NO BLIND PATCHING

When you need to modify a Python file:

1. ✅ FIRST: Use the Read tool to read the ENTIRE file (all lines)
2. ✅ THEN: Check if your change already exists
3. ✅ THEN: Check for duplicates
4. ✅ THEN: Rewrite the WHOLE function/block (not line-by-line insertion)
5. ❌ NEVER: Append code without reading the full file

2. ARGPARSE IS SPECIAL

When modifying argparse code:

• ❌ DO NOT add arguments in multiple places
• ❌ DO NOT call parser.add_argument() twice for the same option
• ✅ DO rewrite the entire build_parser() function
• ✅ DO check the file for existing argument definitions FIRST
• ✅ DO verify no conflicting option strings (like --question)

Example of WRONG approach:

# ❌ BAD: Adding same arg in two places
parser.add_argument("--question", required=True)  # Line 50
parser.add_argument("--question", required=False) # Line 100
# ^ This will throw: argparse.ArgumentError: argument --question: conflicting option string

Example of RIGHT approach:

# ✅ GOOD: Single source of truth
def build_parser():
    parser = argparse.ArgumentParser()
    parser.add_argument("--question", required=False)
    parser.add_argument("--frameworks", nargs="+")
    parser.add_argument("--verbose", action="store_true")
    return parser

3. NO DUPLICATES

Before writing any function:

1. Search the file for function with the same name
2. If it exists, rewrite it (don't add another one)
3. Check for similar function names (typos, variations)
4. Delete the old one if rewriting

4. IMPORTS AT TOP

Never import mid-function:

# ✅ CORRECT: Imports at top
import sys
from pathlib import Path

def main():
    result = sys.exit(0)  # OK to use here

# ❌ WRONG: Import inside function
def main():
    import sys  # No! Import at top
    import random_library  # No!

5. TYPE HINTS REQUIRED

Every function must have type hints:

# ✅ CORRECT
def answer(self, question: str, frameworks: Optional[List[str]] = None) -> ToolResponse:
    ...

# ❌ WRONG (missing types)
def answer(self, question, frameworks=None):
    ...

---

📋 CHECKLIST BEFORE WRITING CODE

Before you generate or modify any code file:

• Have I read the ENTIRE file first?
• Does this function already exist?
• Are there duplicates I should remove?
• Does this follow SRP (single responsibility)?
• Are all functions type-hinted?
• Are imports at the top?
• Is there a docstring?
• Will this create new test failures?

---

🔍 FILE-SPECIFIC RULES

For oracle_answer_mcp.py

CRITICAL: This file had duplicate argparse definitions. If you modify it:

1. Read the ENTIRE build_parser() function
2. Look for ANY parser.add_argument() calls
3. If --question is defined MORE than once, DELETE all but one
4. Check for conflicting flags (argparse won't allow duplicates)

---

For oracle_runner.py

This is stable. Only modify if:

• Bug fix required
• New compliance framework needed
• Performance issue

When modifying:

1. Keep the run() method signature the same
2. Keep OracleAnswer dataclass schema consistent
3. Update COMPLIANCE_LEDGER.jsonl format in docstring

---

For Terraform files

Cloudflare provider is v4.52.5. If updating:

1. Check .terraform.lock.hcl first
2. Run terraform validate after changes
3. Run terraform plan before commit
4. Don't modify resource names (breaks state)

---

⚠️ COMMON MISTAKES (Don't Make These)

Mistake	Symptom	Fix
Duplicate argparse args	ArgumentError: conflicting option string	Delete duplicate definition
Missing type hints	Type checker errors	Add : Type to all params
Append instead of rewrite	Multiple similar functions	Read file, rewrite once
Import mid-function	Code style error	Move imports to top
Subscript None	TypeError: 'NoneType' not subscriptable	Check for None first
Missing docstrings	Code review failure	Add docstrings to all functions

---

🧪 TESTING AFTER CHANGES

After modifying code, run:

# 1. Quick sanity check
bash TEST_WORKFLOW.sh quick

# 2. Test the specific script you changed
python3 oracle_runner.py "test question?"

# 3. Run any affected tests
python3 oracle_answer_mcp.py --tool-info

# 4. Look for errors
python3 -m py_compile oracle_runner.py  # Syntax check

---

🚫 FORBIDDEN PATTERNS

❌ Pattern 1: Blind Appending

# NO! Never do this:
# Read part of file, then append without seeing rest
parser.add_argument("--json")  # Line 200

# ... 100 lines away somewhere:
parser.add_argument("--json")  # DUPLICATE! Conflict!

❌ Pattern 2: Nested Imports

# NO! Never do this:
def process_data():
    import csv  # Should be at top
    import json  # Should be at top
    # ... code

❌ Pattern 3: Type-Free Parameters

# NO! Never do this:
def answer(self, question, frameworks, verbose):  # No types!
    pass

# YES! Do this:
def answer(self, question: str, frameworks: Optional[List[str]], verbose: bool) -> ToolResponse:
    pass

❌ Pattern 4: Patch Editing

# NO! Don't patch one line:
oldString: "def main():\n    ..."
newString: "def main():\n    print('new line')"  # This breaks the function

# YES! Rewrite whole function:
# Read the full main()
# Rewrite it completely
# Replace the entire function

---

✅ CORRECT WORKFLOW

When asked to modify code:

Step 1: Understand

• What is broken?
• What file needs changing?
• What is the whole context?

Step 2: Read

Use the Read tool:
read /path/to/file.py  # Read ENTIRE file

Step 3: Analyze

• Where is the problem?
• Is it already fixed?
• Are there duplicates?
• What is the function signature?

Step 4: Rewrite

Use the Edit tool:
- oldString: [ENTIRE function]
- newString: [Fixed ENTIRE function]

Step 5: Test

python3 file.py --test
bash TEST_WORKFLOW.sh quick

Step 6: Verify

• No new errors?
• No duplicates?
• Tests passing?

---

📞 SUMMARY

Rule	Critical?	Check Before
Read entire file	✅ Yes	Edit anything
No duplicate defs	✅ Yes	Add any function
Argparse centralized	✅ Yes	Modify argparse
Type hints required	✅ Yes	Write any function
Docstrings needed	✅ Yes	Finish any function
Imports at top	🟡 High	Write imports
Tests passing	🟡 High	Commit code

---

🆘 If Something Goes Wrong

You see: argparse.ArgumentError: argument --question: conflicting option string

1. Read oracle_answer_mcp.py line-by-line
2. Find ALL instances of parser.add_argument("--question"...)
3. Keep ONE, delete the others
4. Test: python3 oracle_answer_mcp.py --tool-info

You see: TypeError: 'NoneType' object is not subscriptable

1. Find the line with [...] or .get(...)
2. Add null check: if result: result['key']
3. Test the fix

You see: Import "x" could not be resolved

1. Check if module exists: ls mcp/oracle_answer/*.py
2. Check imports are correct: from .tool import X
3. Check init.py exists

---

Last Updated: December 8, 2025
Status: 🟢 Active
Apply To: All code modifications by agents