# Code Methodology Context ## Best Practices Review Before starting any task: 1. Check if `/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 `/best-practices/` 5. Apply those practices to your work If `/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 `best-practices/test-driven-development.md` and `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: ```python _HAS_OPENAI = True try: import openai except ImportError: _HAS_OPENAI = False ``` Check the flag at call time: ```python 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/.