refactor(AGENTS.md): thin-index §Critical Anti-Patterns to canonical styleguides
Per agent_directives_consolidation_20260705 §3.1. The 9 duplicated items (read full files, modify tech stack, skip TDD, skip markers, batch commits, no comments, set_file_slice, git restore caveat) are now 1-line summaries + pointers to the canonical homes: - conductor/code_styleguides/python.md (LLM Default Anti-Patterns §17) - conductor/code_styleguides/data_oriented_design.md §8.5 (Python Type Promotion Mandate) - conductor/edit_workflow.md (the edit tool contract) - conductor/workflow.md §Known Pitfalls + Skip-Marker Policy The 4 canonical HARD BANs (git restore / git checkout / git reset; git stash*; day estimates; opaque types) remain inline as they are the project-wide rules with no single canonical home. Each HARD BAN now points to its technical mandate for the full rationale. Net effect: AGENTS.md §Critical Anti-Patterns reduced from 14-line section with 13 mixed items to 19-line section with 4 HARD BANs + a thin index. The duplicated content is now in the canonical styleguides where it belongs; the 4 HARD BANs are deduplicated to their one proper home here.
This commit is contained in:
@@ -48,18 +48,18 @@ The 14 deep-dive guides under `docs/` (`guide_architecture.md`, `guide_ai_client
|
||||
|
||||
## Critical Anti-Patterns
|
||||
|
||||
- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary` to map the structure (this is navigation efficiency, not a "files should be small" stance)
|
||||
- Do not modify the tech stack without updating `conductor/tech-stack.md` first
|
||||
- Do not skip TDD - write failing tests before implementing functionality
|
||||
- Do not use `@pytest.mark.skip` as an excuse to AVOID fixing the underlying bug. Skip markers are documentation of known failures; the failure must be addressed with priority in-session when feasible. See `conductor/workflow.md` "Skip-Marker Policy" for the full policy and review checklist.
|
||||
- Do not batch commits - commit per-task for atomic rollback
|
||||
- Do not add comments to source code; documentation lives in `/docs`
|
||||
- `set_file_slice` IS valid for multi-line content. The agent must verify the exact byte offsets with `get_file_slice` first, copy the line text character-for-character (including whitespace and EOL), and check whether the edit changes a public contract (function signature, yield shape, return type) that other code depends on. See `conductor/edit_workflow.md` for the full contract.
|
||||
- Do not use `git restore` while a user is mid-conversation without first confirming the desired state
|
||||
- HARD BAN: `git restore`, `git checkout -- <file>`, `git reset` are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST.
|
||||
- HARD BAN: `git stash*` (any form: `git stash`, `git stash pop`, `git stash apply`, `git stash drop`, `git stash clear`) is FORBIDDEN. Stashing inverts the safety net of the working tree: a `git add .` then `git stash` then "fresh start" pattern is exactly how Tier 2 corrupted files in the 2026-06-27 `cruft_elimination_20260627` track. The user explicitly stated "I hate when people fuck with my commits" — stashing throws away the user's in-progress edits silently. If you think you need a stash, you don't — use a NEW BRANCH or a WORKTREE instead. Tier 2 sandbox enforces this via `conductor/tier2/opencode.json.fragment` bash deny rules.
|
||||
- **HARD BAN: Day estimates in track artifacts (Tier 1).** Do NOT include day / hour / minute estimates in spec.md, plan.md, metadata.json, or any other track artifact. Day estimates are inaccurate noise; Tier 2 capacity is bounded by attention, not time. Measure effort by **scope** (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.")
|
||||
- **HARD BAN: Opaque types in non-boundary code (added 2026-06-25).** LLMs default to `dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` polymorphism, and `.get('field', default)` because that's idiomatic Python training data. **All of these are BANNED in non-boundary code.** Use typed `@dataclass(frozen=True, slots=True)` with explicit fields; use `Result[T]` + `NIL_T` sentinels instead of `Optional[T]`; use direct attribute access instead of `.get()`. The ONLY place `dict[str, Any]` is allowed is the literal wire boundary (TOML/JSON parse functions); 2-3 functions per file. See `conductor/product-guidelines.md` "Core Value", `conductor/code_styleguides/data_oriented_design.md` §8.5 (The Python Type Promotion Mandate), `conductor/code_styleguides/python.md` §17 (LLM Default Anti-Patterns), and `conductor/code_styleguides/type_aliases.md` for the canonical mandates. User direction 2026-06-25: "I want the closest thing to c11/odin/jai in a scripting language... metadata should not be a dict[str, any]."
|
||||
This is a thin index. For the full lists, see the canonical styleguides:
|
||||
- `conductor/code_styleguides/python.md` §"AI-Agent Specific Conventions" + §"Anti-Patterns (LLM Default Anti-Patterns)" — the full LLM anti-pattern list (navigation, no comments, no diagnostic noise, TDD, decorator-orphan, ast.parse, set_file_slice, etc.)
|
||||
- `conductor/code_styleguides/data_oriented_design.md` §8.5 — the Python Type Promotion Mandate (technical canonical for opaque types)
|
||||
- `conductor/edit_workflow.md` — the edit tool contract
|
||||
- `conductor/workflow.md` §"Known Pitfalls" + §"Skip-Marker Policy" — operational pitfalls
|
||||
|
||||
### The 4 canonical HARD BANs (in this file because they're project-wide)
|
||||
|
||||
- **HARD BAN: `git restore` / `git checkout -- <file>` / `git reset`** are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST.
|
||||
- **HARD BAN: `git stash*`** (any form: `git stash`, `git stash pop`, `git stash apply`, `git stash drop`, `git stash clear`) is FORBIDDEN. Stashing inverts the safety net of the working tree: a `git add .` then `git stash` then "fresh start" pattern is exactly how Tier 2 corrupted files in the 2026-06-27 `cruft_elimination_20260627` track. The user explicitly stated "I hate when people fuck with my commits" — stashing throws away the user's in-progress edits silently. If you think you need a stash, you don't — use a NEW BRANCH or a WORKTREE instead. Tier 2 sandbox enforces this via `conductor/tier2/opencode.json.fragment` bash deny rules.
|
||||
- **HARD BAN: Day / hour / minute estimates in track artifacts.** Do NOT include estimates in spec.md, plan.md, metadata.json, or any other track artifact. Measure effort by **scope** (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.")
|
||||
- **HARD BAN: Opaque types in non-boundary code (added 2026-06-25).** `dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` for entity dispatch, `.get('field', default)` are BANNED. Use typed `@dataclass(frozen=True, slots=True)` + `Result[T]` + `NIL_T` sentinels + direct attribute access. The ONLY place `dict[str, Any]` is allowed is the literal wire boundary (TOML/JSON parse functions); 2-3 functions per file. See `conductor/code_styleguides/data_oriented_design.md` §8.5 (the canonical Python Type Promotion Mandate), `conductor/code_styleguides/python.md` §17, `conductor/code_styleguides/type_aliases.md` for the technical mandates. User direction 2026-06-25: "I want the closest thing to c11/odin/jai in a scripting language... metadata should not be a dict[str, any]."
|
||||
|
||||
## File Size and Naming Convention (HARD RULE — added 2026-06-11)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user