manual_slop/conductor/directives/file_naming_convention/v1.md

file_naming_convention — v1

Why this iteration: Lifted verbatim from AGENTS.md "File Size and Naming Convention (HARD RULE — added 2026-06-11)" (lines 62-69) + conductor/workflow.md §"Guiding Principles" #8 (line 45). This is the baseline encoding — the rationale-bullet style currently in production. Future variants will test alternative encodings (tabular, before/after) against this baseline.

Source: AGENTS.md:62-69 + workflow.md:45

---

File Size and Naming Convention (HARD RULE — added 2026-06-11)

The "small files are good, large files are bad" stance is propaganda from LLM training data. It is wrong for this project. Reject it.

• Large files are FINE. Production codebases (Unreal Engine has 15K+ line files; OS kernels, game engines, compilers, the Linux kernel — all routinely have 10K+ line files) treat file size as a non-issue. Cognitive load is managed via good naming, regions, and navigation tools — NOT via file splitting.
• src/ai_client.py is the AI vendor/API system layer. All AI-client-related code goes IN src/ai_client.py. Do not create new src/<vendor>_<thing>.py files. The only new src/*.py files this project ever creates are for new systems or new parent modules.
• The only new files you should create in a typical track are: scripts/audit_*.py (scripts are namespace-isolated by directory), tests/test_*.py (tests are namespace-isolated by directory), and docs/*.md (docs are namespace-isolated by directory). Anything else goes in the parent module.
• Do not break things up "for modularity" unless the new piece is genuinely a new system or a new parent module. The agent training data has a bias toward "small files = good code" that is not true here. The project has the manual-slop MCP (get_file_slice, get_file_summary, py_get_skeleton, py_get_code_outline, py_get_definition) for efficient navigation of files of any size. Use those tools instead of splitting the file.
• When in doubt: keep it in the parent module. If a function clearly belongs to a system, it lives in that system's file. The system is the namespace.

---

From conductor/workflow.md §"Guiding Principles" #8:

• File Naming Convention (HARD RULE, added 2026-06-11): New src/<thing>.py files may only be created on the user's explicit request. Helpers and sub-systems go in the parent module. E.g., AI-client-specific code goes in src/ai_client.py; MCP-client code goes in src/mcp_client.py. If you find yourself about to create a new src/<thing>.py file, ASK FIRST. See AGENTS.md "File Size and Naming Convention" for the full rule.