chemenu/kb/concepts/decisions/Diff-Reviewable Agent Edits.md

---
type: types/concept.md
concept_type: decision
tags: [agent-workflow, context-engineering, tooling]
created: 2026-08-31
modified: 2026-08-31
related:
  - see-also: Claude Code Auto Mode
  - operates-on: Claude Code
  - derived-from: Write-Once Frontmatter Fields
sources: [Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]
provenance: sourced
summary: Entscheidung, Dateiaenderungen ueber Edit/Write statt ueber Shell-Heredocs zu fahren, weil nur das erste eine pruefbare Diff hinterlaesst
---
# Diff-Reviewable Agent Edits

**Typ:** Decision

## Definition

Ein Agent ändert Dateien über die dedizierten Werkzeuge `Edit` und `Write`, nicht über
Shell-Konstrukte wie `sed -i`, Heredocs oder eingebettete Skripte. Die Shell bleibt für alles
zuständig, was keine Datei umschreibt: `git`, `pytest`, [[wikitool]], `grep`, `find`, und Lesen
mit `cat` oder `sed -n`.

## Kontext

Der aktive Berechtigungsmodus [[Claude Code Auto Mode]] injiziert eine Anweisung in die Sitzung,
die genau das Gegenteil verlangt: Arbeit möglichst über das Bash-Werkzeug erledigen und auf ein
dediziertes Werkzeug erst zurückfallen, wenn Bash die Aufgabe nicht bewältigt. Der Assistent war
ihr gefolgt und hatte `lint.py`, `frontmatter_io.py` und `run_budget.py` über heredoc'te
`python3 - <<'PY'`-Blöcke mit `s.replace(old, new)`
umgeschrieben[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31]. Torben hat das
abgestellt:
*"Warum verwendest du seit neuestem immer die Shell um Dateien zu editieren anstelle der file
edit Tools? Das macht die Session schwer nachvollziehbar."*

## Entscheidung

`Edit`/`Write` für Dateiänderungen, Bash für Prozesse. Die Regel wurde in das dauerhafte
Gedächtnis des Assistenten geschrieben, damit sie die Sitzung
überdauert[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31].

Zwei Gründe tragen sie, und der zweite ist der belastbarere:

1. **Die ausdrückliche Anweisung des Nutzers rangiert über einer Modus-Voreinstellung.**
2. **Die Anweisung des Modus schlägt sich selbst.** Ihr Qualifikator lautet *"wherever it can
   accomplish the job"*. Ein `s.replace(old, new)` in einem Heredoc zeigt dem Leser zwei
   String-Literale und keine Änderungsansicht: was vorher in der Datei stand und was jetzt darin
   steht, ist nicht sichtbar. Ein Edit, dessen Diff niemand prüfen kann, erfüllt die Aufgabe
   nicht - also greift der Vorrang der Shell an dieser Stelle gar nicht erst.

## Konsequenzen

- Die Grenze verläuft zwischen **Lesen** und **Schreiben**, nicht zwischen Shell und Werkzeug.
  `cat`, `head`, `sed -n`, `grep` und `find` bleiben unverändert zulässig.
- Sie verläuft nicht bei jeder Änderung gleich scharf: bei einem einzeiligen `sed` ist der
  Unterschied unerheblich, beim Mehrblock-Umbau eines Compiler-Moduls nicht. Die Regel wird
  trotzdem einheitlich angewandt, weil die Einschätzung "das ist klein genug" genau die ist, die
  im Zweifelsfall zugunsten der Bequemlichkeit ausfällt.
- Der Modus lässt sich nicht so einstellen, dass nur diese Präferenz entfällt; es wurde keine
  solche Einstellung
  gefunden[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31]. Die Regel muss also
  als Verhaltensregel getragen werden, nicht als Konfiguration.
- In diesem Repository fällt die Entscheidung mit den Interessen des Stacks zusammen: was
  `wikitool` erzeugt, wird ohnehin nie von Hand geschrieben, und was von Hand geschrieben wird,
  soll im Publish-Diff nachlesbar sein.

## Status

Angenommen (2026-08-31), auf Anweisung des Nutzers, für Sitzungen an diesem Repository.

## Verwandte Concepts

- [[Claude Code Auto Mode]]

## Beziehungen

## Siehe auch

- [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]

## Fußnoten

[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31]: [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]

<!-- wikitool:links -->
## Beziehungen

- **see-also:** [[Claude Code Auto Mode]]
- **operates-on:** [[Claude Code]]
- **derived-from:** [[Write-Once Frontmatter Fields]]
<!-- /wikitool:links -->