Private
Public Access
0
0

feat(directives): harvest 3 file/taxonomy directives from AGENTS.md + workflow.md

This commit is contained in:
2026-07-02 22:02:35 -04:00
parent 462860de54
commit fa488ccfc6
3 changed files with 59 additions and 0 deletions
@@ -0,0 +1,23 @@
# 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.
@@ -0,0 +1,18 @@
# large_files_are_fine — v1
**Why this iteration:** Lifted verbatim from `AGENTS.md` "File Size and Naming Convention (HARD RULE — added 2026-06-11)" (lines 62-67). 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-67`
---
## 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.
@@ -0,0 +1,18 @@
# no_new_src_files_without_permission — v1
**Why this iteration:** Lifted verbatim from `AGENTS.md` "Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)" (lines 71-78). 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:71-78`
---
### Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)
**New namespaced `src/<thing>.py` files may only be created on the user's explicit request.** If you find yourself about to create one, **ASK FIRST** — don't just create it.
Rationale: the user is the only one who can authorize a new top-level namespace. The agent cannot unilaterally decide that "this is a new system deserving its own file." Defaults:
- **Helpers and sub-systems go in the parent module.** E.g., AI-client-specific helpers go in `src/ai_client.py`; app-controller helpers go in `src/app_controller.py`; MCP-client helpers go in `src/mcp_client.py`. Even if the parent file is already 3K+ lines, the helper still goes there.
- **If a new top-level `src/<thing>.py` is genuinely warranted** (e.g., a truly new system that doesn't fit any existing parent), propose it in the next checkpoint or status note and wait for the user's explicit "yes, create it."
**Audit trigger:** if you find yourself about to create a new `src/<thing>.py` file, ask: "is `<thing>` a new system, or is it part of an existing system?" If it's part of an existing system, the file goes in that system's file (e.g., `src/ai_client.py`, `src/app_controller.py`, `src/mcp_client.py`, etc.). If it's a new system, ASK THE USER before creating the file.