Read-before-edit — brama przed edycją pliku

Zasada

Każdy plik, który edytujesz, musiał być przeczytany w tej samej sesji.

Nie w poprzedniej sesji. Nie "kiedyś". W tej sesji.

Dlaczego

• Pliki zmieniają się między sesjami (Ty lub inny agent commitujesz)
• Pamięć agenta jest niewiarygodna — "wydaje mi się, że wiem co tam jest"
• Nadpisanie bez odczytania = utrata cudzej pracy
• Narzędzia Edit wymagają exact match — bez Read najnowszej wersji Edit faila

Flow

Zamierzasz zmienić plik X?
  └── Czy czytałeś X w tej sesji?
        ├── TAK → Edit / Write
        └── NIE → Read X najpierw, potem Edit / Write

Praktyczne zasady

1. Read zawsze przed pierwszym Edit w sesji

Agent: [Read /path/to/file.ts]
Agent: [Edit /path/to/file.ts — stare: X, nowe: Y]

2. Re-read po długich operacjach

Jeśli między Read a Edit:

• Uruchomiłeś długi build / test
• Agent-subagent modyfikował repo
• Przełączyłeś branch
• Minął znaczny czas / duża liczba tool calls

→ re-read zanim zaufasz pamięci.

3. Write-new-file nie wymaga Read

Jeśli plik nie istnieje → Write bezpośrednio. Ale upewnij się że nie istnieje:

Agent: [Glob /path/to/new-file.ts] → brak wyników
Agent: [Write /path/to/new-file.ts ...]

Bez Glob możesz nadpisać istniejący plik myśląc, że tworzysz nowy.

4. Bulk edit przez sed/awk — zabronione

Harness nie pozwala na bulk edit przez Bash (sed -i, awk '...' > file). Dlaczego:

• Bez odczytu diff jest nieznany
• Regex na produkcyjnym kodzie = ryzyko
• Edit tool ma exact match, safer

Wyjątek: jeśli bulk rename jest udokumentowany w planie i zweryfikowany (sprawdzisz diff po), użyj rg / grep najpierw dla listy match, potem Edit per plik.

Red flags

• ❌ "Z pamięci wiem, że ten plik ma funkcję X" → re-read
• ❌ "Edytuję plik, którego nie otwierałem, ale wiem co robi" → STOP, Read
• ❌ "Pominę Read, bo znam strukturę" → pamięć cię okłamuje, Read
• ❌ "Plik się nie zmienił od ostatniego Read 30 minut temu" → może się zmienił, Read

Co robić, gdy Edit faila na "string not found"

To znak, że masz stary snapshot w pamięci:

1. Re-read ten plik od nowa
2. Znajdź aktualny fragment
3. Zaktualizuj old_string do aktualnej zawartości
4. Edit ponownie

NIE:

• Próbuj innego regexa
• Zmień replace_all: true "żeby zadziałało"
• Użyj sed/awk jako fallback

Integracja z innymi skillami harness

• Plan-before-code: plan powinien listować pliki do edycji — każdy z nich trzeba najpierw Read
• Phase continuity brief: brief pokazuje commits od ostatniej sesji → pliki, które się zmieniły, wymagają Read przed dotknięciem
• Tool failed → STOP: Edit fail = tool failed = STOP i diagnoza (re-read)

Automatyzacja (opcjonalne)

W ~/.claude/settings.json możesz dodać hook PreToolUse dla Edit/Write, który sprawdza czy plik był Read w sesji. Zbyt agresywny hook blokuje legit flows — polegaj głównie na dyscyplinie.

Efekt

• Zero nadpisanej cudzej pracy
• Zero "magicznych" konfliktów merge
• Edit zawsze działa od pierwszego strzału (exact match z aktualną wersją)
• Audit trail sesji pokazuje parę Read → Edit per plik (łatwo review)