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

Code Methodology (MiniMax)

Rules (MUST follow — task fails if violated)

0. NEVER use Write on existing files. Use Edit for ALL modifications to existing files.
   • Read the file first (Read tool), then use Edit for targeted changes only.
   • Write is only for creating new files that do not yet exist.
1. ONLY modify files directly related to your task. Do NOT touch other files.
2. ONLY run the specific test file for your feature. NEVER run the full test suite.
3. If something fails after 3 attempts with the same approach, try a COMPLETELY different approach.
4. Do NOT create backup copies of files or directories.
5. Do NOT rename existing files before modifying them.

How to Work

1. Read the task description carefully.
2. Read the files mentioned in the task.
3. If a spec file is referenced, find the specific requirement by ID. Implement exactly that requirement.
4. Look at an existing file similar to what you are creating. Copy its structure. Change only the parts specific to your task.
5. Make changes in small steps.
6. After each change, run ONLY your specific test file:

python -m pytest tests/test_YOUR_FILE.py -v --tb=short -x

WRONG (NEVER do this):

python -m pytest tests/ -v
python -m pytest
pytest

7. If tests pass, write a summary and stop.

When You Get Stuck

If the same error appears 3 times:

• STOP trying the same fix.
• Read the error message ONE more time.
• Ask: "Am I looking at the right file?"
• Ask: "Should I mock this instead of fixing it?"
• Try the opposite approach.

If a directory or file does not exist where you expect it:

• Do NOT debug the environment.
• Mock it or create a test fixture instead.

Python Conventions

• Python 3.12+ with type hints
• Pydantic v2 for data models
• pytest for testing
• Structured JSON logging
• Configuration via environment variables

Python Safety Rules

Module Imports

Never call sys.exit() at module level or inside except ImportError. Use a flag:

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

Pydantic Validators

• Use @model_validator(mode='after') for cross-field validation
• @field_validator does NOT fire for default values

Async Tests

• Async test functions must be async def with @pytest.mark.asyncio
• A sync def test_ that calls async code silently passes without executing

Session Logging

Write a brief session log to /project/memory/log/<date>.<time>.md with:

• Summary: One paragraph
• Gotchas: Issues with topic tags (e.g., [python])

Omit empty sections. Keep it short.