docs(workflow,agents): remove 'large files are bad' propaganda; add naming rule

The user called out the LLM training data bias: 'small files are
good, large files are bad.' This is wrong for production codebases.
Unreal has 15K+ line files; OS kernels, game engines, compilers all
routinely have 10K+ line files. File size is a non-issue. Cognitive
load is managed via naming, regions, and navigation tools (the
manual-slop MCP) — NOT via file splitting.

Updates:

1. AGENTS.md (master agent guidance):
   - Added 'File Size and Naming Convention' section
   - Added the hard rule: '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.'
   - Defaults: helpers and sub-systems go in the parent module

2. conductor/workflow.md (Guiding Principles):
   - Removed 'Do NOT perform large file writes directamente' from
     principle 7 (it was a delegating rule, but 'large file writes'
     carried the propaganda)
   - Added principle 8: 'File Naming Convention (HARD RULE)' that
     references AGENTS.md
   - Re-phrased principle 9 (Research-First) to clarify it's about
     navigation efficiency, not file size

3. conductor/code_styleguides/python.md:
   - Removed the 'extremely large files that violate the Anti-OOP
     rule by necessity' framing
   - Added the new rule about new src/<thing>.py files

4. .opencode/agents/tier3-worker.md and .opencode/agents/tier4-qa.md:
   - Re-phrased 'Do NOT read full large files' to 'Use skeleton
     tools to navigate any file regardless of size. File size is
     not a concern; the right tools are.'
   - Added the new rule about not creating new src/<thing>.py
     files unless user explicitly requests it

5. conductor/tracks/qwen_llama_grok_followup_20260611/plan.md:
   - Updated the 'Naming Convention' section to reference the new
     'user explicit request' rule

This is docs-only. No code changes. The rule is now codified:
agents must ASK FIRST before creating new top-level src/ files.
This commit is contained in:
ed
2026-06-11 10:07:07 -04:00
parent 4e4a56fd08
commit 51edbdef20
6 changed files with 151 additions and 41 deletions
+2 -1
View File
@@ -40,7 +40,8 @@ with open('file.py', 'w', encoding='utf-8', newline='') as f:
4. **High Code Coverage:** Aim for >80% code coverage for all modules
5. **User Experience First:** Every decision should prioritize user experience
6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
7. **MMA Tiered Delegation is Mandatory:** The Conductor acts as a Tier 1/2 Orchestrator. You MUST delegate all non-trivial coding to Tier 3 Workers and all error analysis to Tier 4 QA Agents. Do NOT perform large file writes directly.
7. **MMA Tiered Delegation is Mandatory:** The Conductor acts as a Tier 1/2 Orchestrator. You MUST delegate all non-trivial coding to Tier 3 Workers and all error analysis to Tier 4 QA Agents. Do NOT write non-trivial code directly.
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.
8. **Mandatory Research-First Protocol:** Before reading the full content of any file over 50 lines, you MUST use `get_file_summary`, `py_get_skeleton`, `py_get_code_outline`, or `py_get_docstring` to map the architecture and identify specific target ranges. Use `get_git_diff` to understand recent changes. Use `py_find_usages` to locate where symbols are used.
9. **Architecture Documentation Fallback:** When uncertain about threading, event flow, data structures, or module interactions, consult the deep-dive docs in `docs/` (last refreshed: 2026-06-02 via the comprehensive documentation refresh track, **8 new guides added**):
- **[docs/guide_architecture.md](../docs/guide_architecture.md):** Thread domains, cross-thread patterns, AI client multi-provider (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax), HITL Execution Clutch.