ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(styleguide): add No-Diagnostic-Noise rule to AI-Agent Conventions

Browse Source 
One addition to conductor/code_styleguides/python.md §8
"AI-Agent Specific Conventions":

- **No diagnostic noise in production code (Added
  2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...") lines
  in src/*.py are technical debt. The right place for
  one-time investigation output is tests/artifacts/<test>.diag.log
  (a log file) or a standalone /tmp/diag_<name>.py script.
  If you must instrument production code, the diag lines
  are part of the same atomic commit as the fix.

- **Test files ARE allowed to be diagnostic.** The rule
  applies to src/*.py only; tests/test_*.py may use
  print(..., file=sys.stderr) freely.

Markdown only. No code modified.
This commit is contained in:
conductor-tier2
2026-06-09 14:03:18 -04:00
parent 631c40c9c4
commit ac0c0cbe73
1 changed files with 2 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/code_styleguides/python.md
+2
View File
@@ -67,6 +67,8 @@ is processed by AI agents, while preserving readability for human review.
- **No empty `__init__.py` files.**
- **Minimal blank lines.** Token-efficient density is preferred over visual padding.
- **Short variable names are acceptable** in tight scopes (loop vars, lambdas). Use descriptive names for module-level and class attributes.
- **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...")` lines added to `src/*.py` for one-time debugging are technical debt the moment they ship. The project's production code should not contain `[XYZ_DIAG]` markers, `print(...debug...)` calls, or any other ad-hoc debug instrumentation. The right place for diagnostic output during a one-time investigation is `tests/artifacts/<test_name>.diag.log` (a log file) or a standalone `/tmp/diag_<name>.py` script. If you must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted.
- **Test files ARE allowed to be diagnostic.** `tests/test_*.py` may use `print(..., file=sys.stderr)` freely for test output. The rule against diagnostic noise applies to `src/*.py` only.
## 10. Anti-OOP Conventions