keep-the-caveat-with-the-number
Liczba i jej zastrzeżenie muszą być jednym artefaktem. Dwa akapity się rozjeżdżają; jeden komponent nie może.
Nadane przez osobę, która przeczytała kartę, a nie deklarowane przez sam plik. Karta, którą agent destyluje podczas przebiegu z niezaufaną treścią, rodzi się skażona i czeka na recenzję, zanim kiedykolwiek zostanie pobrana.
Kiedy przychodzi na myśl
- publikowanie wyniku benchmarku
- wstawianie metryki na stronę
- liczba wymaga kontekstu
- podsumowanie pomiaru
Wartość zwykle kryje się w Unikaj i Sprawdź. Rób to sekcja, którą pisze każdy.
Treść karty powyżej to tłumaczenie. Angielski oryginał jest tym, co importuje CLI, co agent czyta w czasie działania i czego dotyczy hasz poniżej.
Wyzwalacz
Umieszczasz zmierzoną wartość tam, gdzie zobaczy ją czytelnik: w README, na landing page, w release notes, na dashboardzie, w raporcie. Wartość jest prawdziwa i potrzebuje obok siebie zdania, żeby nie wprowadzać w błąd — próbka była mała, wycinek był łatwy, efekt nie był istotny statystycznie, benchmark był nasz.
Nie dotyczy to wartości, której znaczenie jest kompletne samo w sobie. "Build trwał 41 sekund" nie potrzebuje niczego.
Rób
- Napisz zastrzeżenie najpierw, przed liczbą. Jeśli nie potrafisz ująć ograniczenia w jednym zdaniu, jeszcze nie rozumiesz pomiaru na tyle, żeby go publikować.
- Spraw, by zastrzeżenie było strukturalnie przypięte. Umieść je w tym samym komponencie, tym samym wierszu tabeli, tej samej zwracanej wartości funkcji — czymś, co nie może wyrenderować liczby bez niego.
- Umieść je nad liczbą albo obok niej. Nie pod nią.
- Spraw, by sama liczba była wyprowadzana: odczytuj ją z artefaktu, który wyprodukował pomiar, żeby poruszała się razem z pomiarem.
Unikaj
Liczba w nagłówku, a zastrzeżenie w przypisie, gwiazdce, zwiniętej sekcji albo akapicie poniżej. Wszystkie to ten sam błąd w innej stylizacji: czytelnik formuje przekonanie najpierw, a poprawka przychodząca później musi pokonać przekonanie, które już istnieje.
Unikaj też wersji drugiego rzędu — komponentu, który może wyrenderować liczbę z pominiętym zastrzeżeniem. Jeśli zastrzeżenie jest argumentem opcjonalnym, zostanie pominięte, i pominie je ktoś, kto skraca akapit, wcale nie zamierzając zmienić znaczenia.
I nie parafrazuj zastrzeżenia, które zostało napisane starannie. Przeredagowanie to moment, w którym "nieistotne samo w sobie" zamienia się w "bliskie istotności".
Sprawdź
Spróbuj napisać liczbę bez zastrzeżenia i patrz, jak to zawodzi. Usuń argument z zastrzeżeniem albo umieść gołą liczbę na stronie i uruchom build.
Jeśli się skompiluje, powiązanie jest konwencją, a nie mechanizmem, a konwencje przetrwają dokładnie tak długo, jak długo nikt się nie spieszy.
Ryzyko
Zastosowane nadmiernie, sprawia, że zwykłe raportowanie staje się ciężkie: nie każda liczba jest benchmarkiem, a zastrzeżenie przy liczbie, która go nie potrzebuje, uczy ludzi pomijać zastrzeżenia.
Trudniejsze ryzyko polega na tym, że mechanizm wydaje się całą odpowiedzią. Komponent, który zawsze renderuje jakieś zastrzeżenie, nie sprawdza, czy to zastrzeżenie jest właściwe. Zdanie musi wciąż zostać napisane uczciwie przez człowieka; to tylko powstrzymuje je przed późniejszym usunięciem.
Jak użyć
Karta to dane. Sklonuj repozytorium i zaimportuj ją ścieżką — to, co przychodzi przez sieć, jest traktowane jako skażone i wstrzymywane do zatwierdzenia. Taki jest pożądany sposób działania i dlatego nie ma tu instalatora w jednej linijce.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdIntegralność
SHA-256 pliku w postaci opublikowanej. Importujący może sprawdzić, że otrzymał dokładnie to, co pokazała ta strona.
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6