agent-runtime-framework/harnesses/contexts/code-methodology/v1/CLAUDE.md

Code Methodology Context

Best Practices Review

Before starting any task:

1. Check if /workspace/best-practices/INDEX.md exists
2. If it exists, read it to see available topics
3. Identify relevant topics for the current task:
   • Python task → read test-driven-development.md, spec-driven-development.md
   • Kubernetes task → read kubernetes.md
   • Shell scripts → read scripting.md
4. Read the relevant topic files from /workspace/best-practices/
5. Apply those practices to your work

If /workspace/best-practices/ doesn't exist, proceed without — it's not mandatory.

Spec-Driven Development Workflow

1. Read the spec — Read relevant files in spec/ before writing any code
2. Write tests first — Create test cases from spec requirements before implementing (see /workspace/best-practices/test-driven-development.md and /workspace/best-practices/spec-driven-development.md if available)
3. Implement iteratively — Build implementation to satisfy tests and spec
4. Write session log — Document what was accomplished, decisions made, and gotchas discovered

Conventions

• Python 3.12+ with type hints throughout
• Pydantic v2 for all data models and settings
• pytest for testing with clear, descriptive test names
• Structured JSON logging for all output
• Configuration via environment variables — no hardcoded config
• No shell scripts inside containers — use Python for error handling

Code Quality Rules

• Do not add features, refactor code, or make improvements beyond what was asked
• Validate inputs at system boundaries only, trust internal interfaces

Agent Safety Rules

These rules exist because container agents have repeatedly made these mistakes in production runs.

Python Module Safety

Never call sys.exit() at module level or inside except ImportError blocks. This causes import failures in other modules that import this one. Use a flag pattern instead:

_HAS_OPENAI = True
try:
    import openai
except ImportError:
    _HAS_OPENAI = False

Check the flag at call time:

def use_openai():
    if not _HAS_OPENAI:
        raise RuntimeError("openai is not installed")
    ...

Pydantic Validators

• Use @model_validator(mode='after') when validation needs cross-field access or must fire for default values
• @field_validator only fires when a field is explicitly provided — it will not run for fields that fall back to their default

File Editing Policy (CRITICAL)

NEVER use the Write tool on any file that already exists in /project.

This is the single most important rule. Container agents have repeatedly destroyed complex source files (1000+ lines) by writing new minimal stub versions. The effects are catastrophic and hard to detect because the task still "succeeds" (exit 0).

The correct workflow for modifying any existing file:

1. Read the file first (Read tool)
2. Edit with targeted changes (Edit tool) — ONLY the specific function, class, or field
3. Never rewrite an entire file from scratch with Write
4. Never "simplify" or "restructure" a file unless that is the explicit task

The Write tool is ONLY for creating brand-new files that do not yet exist.

Other file management rules:

• Never create backup copies of files or directories before modifying them
• Edit files in place — do not create paths ending in _orig, _old, _bak, or _backup
• Do not rename existing files or directories before modifying them
• In automated runs there is no one to clean up junk directories

Async Test Patterns

• Test functions for async code must be async def decorated with @pytest.mark.asyncio
• A sync def test_ function that calls an async function receives a coroutine object, not the result — the test will silently pass without executing the async logic

Session Logging

Write a session log to /project/memory/log/<date>.<time>.md (e.g., 2026-03-24.041500.md) with:

• Summary: One paragraph of what was accomplished
• Decisions: Key choices made and reasoning
• Gotchas: Issues discovered with topic tags (e.g., [python], [docker])
• Open Questions: Unresolved items for follow-up
• Process Notes: What worked well, areas for improvement

Omit empty sections.