Ajan Planınız Tasarım Dokümanınızdan Uzun Olmalı

Geliştirdiğim bir filo ve lojistik platformunun kod deposunda ajana dönük dokümanlar iki dizine ayrılıyor: docs/superpowers/specs/ tasarım dokümanlarını, docs/superpowers/plans/ uygulama planlarını tutuyor. İkisi de yönettiğim Claude Code oturumlarından çıkıyor: önce spec’i onaylıyorum, plan ardından o spec’e göre yazılıyor. İki dizini wc -l ile saydım: 36 spec toplam 6.765 satır, ortalama yaklaşık 188; 45 plan toplam 38.639 satır, ortalama yaklaşık 859. Yürütülebilir plan, uyguladığı tasarımdan dört ila beş kat uzun.

Doküman türü	Adet	Toplam satır	Ortalama
Tasarım spec’i (docs/superpowers/specs/)	36	6.765	~188
Uygulama planı (docs/superpowers/plans/)	45	38.639	~859

Bu terslik bilinçli. Tasarım, ne inşa ediyoruz ve neden sorusuna cevap verir. Plan ise ne ters gidecek ve ajanın buna ne yapmasına izin var sorusuna; ikinci soru daha çok kelime ister. Planın işi, işi tarif etmek değildir; ajanın aksi halde sessizce, hem de karar vermeye en donanımsız olduğu anda vereceği kararları önceden vermektir.

Gerçek bir kod tabanında kodlama ajanı (Claude Code, Codex, Cursor) çalıştırıyor, zaten plan yazıyor, ama oturumların başarıyla bitmiş görünüp zor kısmı sessizce atladığını hâlâ görüyorsanız, devamı bu soruna bakıyor. 45 planımın paylaştığı iskeleti, yayına aldığım tek bir değişiklik üzerinden bölüm bölüm geziyorum: rota optimizasyonu yapan bir worker için önbelleğe alınmış yol mesafesi matrisi. İskelet isim verilecek kadar oturmuş: 45 planın 44’ü adımları - [ ] onay kutularıyla takip ediyor, 26’sı File Structure tablosu, 10’u Global Constraints bölümü taşıyor.

Kök nedeni aynı beş arıza#

Aşağıdaki arızaların hepsini kendi oturumlarımda yaşadım.

• Sessiz downgrade. Ajan entegrasyon testini bu ortamda çalıştıramıyor, yerine unit test yazıyor, başarı raporluyor ve negatif senaryonun artık kapsanmadığını hiç söylemiyor. Haziran 2026 tarihli bir makale bu genel örüntüye building to the test (yeni sekmede açılır) adını veriyor: ajan kontrol edilen sinyali tatmin ediyor; istenen davranışın gerçekten var olup olmadığı açık bir soru olarak kalıyor.
• Yardımsever refactor. İki handler aynı sorgu şeklini paylaşıyor diye ajan bunları birleştiriyor; PR artık kimsenin dokunmasını istemediği, iyi test edilmiş bir handler’a dokunuyor.
• Görünmez ihlal. Ajan repo kuralına harfi harfine uyuyor ve kuralı fiilen bozuyor, çünkü kural yanlış seviyede yazılmış. Kapanış bölümünde yayına aldığım bir örneği var.
• Bayat koordinatlar. Plan, o günden beri rebase edilmiş bir dosyaya karşı yazılmış; ajan 254. satırı tam bir özgüvenle takip edip yanlış yere varıyor.
• Kayıtsız kapsam kayması. İşin ortasında ajan bir şeyin kapsam dışı olduğuna karar veriyor. Review’da ortaya çıkıyor; yazılı bir gerekçe hiç olmamış.

Bunların hiçbiri model yeteneği arızası değil. Her birinde verilmesi gereken bir karar var, karşılığında yazılı bir talimat yok ve ajan bir cevap seçip seçimini işaretlemiyor. Planlarımda tekrar eden altı bölüm, bu kararları önceden vermek için var:

Plan bölümü	Kapattığı arıza
Global Constraints	Görünmez ihlal
File Structure	Yardımsever refactor
Deliberately not in this plan	Kayıtsız kapsam kayması
Notes for the implementing engineer	Sessiz downgrade
Concurrent work — resolved	Bayat koordinatlar
Acceptance verification	Kanıtsız tamamlanma iddiası

İzlenecek vaka#

Değişiklik şu: ayrık adres evreni üzerinden tek bir yol mesafesi matrisini S3’te önbelleğe almak; böylece tekrarlanan optimizasyon işleri rota motoruna sıfır çağrı yapıyor. Ortadan kalkan çağrı bir OSRM Table isteği (yeni sekmede açılır): bir koordinat kümesi için tüm çiftlerin sürelerini, annotations=duration,distance istendiğinde de mesafelerini döndürüyor.

Plana ihtiyaç duymasının nedeni bütçe. Rota optimizasyonu worker’ı, Lambda’nın 900 saniyelik zaman aşımı (yeni sekmede açılır) tavanının, yani yükseltilemeyen üst sınırın altında asenkron çalışıyor. Bin duraklı ölçekte yalnızca matris inşasının bu bütçenin 5 ila 7 dakikasını yiyeceği öngörülmüştü. Önbellek nefes payı kazandırıyor. Ama sessiz bir arıza moduyla geliyor: önbellekteki matris yanlışsa rotalar değişiyor ve hiçbir şey hata vermiyor. Yüksek değer artı sessiz arıza, planın uzunluğunu hak ettiği kombinasyonun ta kendisi.

Buradan sonra izlenecek dört artefakt:

1. Tasarım spec’i: 184 satır.
2. Uygulama planı: 1.330 satır, beş görev.
3. Dev flag arkasında yayına aldığım değişiklik (#944).
4. Üç gün sonra merge ettiğim düzeltme (#948): dört satır kaynak kod.

Dördüncü artefakt, hikâyenin bittiği yer.

Doküman zinciri#

Dokümanlar, Claude Code üzerinde sabit bir skill zincirinden çıkıyor: superpowers (yeni sekmede açılır) seti. Buradaki skill, ajanın çağrıldığında yüklediği bir Markdown talimat dosyası (yeni sekmede açılır); dolayısıyla zincir herkes tarafından yeniden kurulabilir:

1. superpowers:brainstorming daha hiçbir şey yazılmadan niyeti sorguya çekiyor.
2. Onayladığım tasarım docs/superpowers/specs/<date>-<slug>-design.md yoluna iniyor.
3. superpowers:writing-plans spec’i görev görev ilerleyen bir plana çeviriyor (docs/superpowers/plans/ altında).
4. superpowers:using-git-worktrees yürütmeyi izole ediyor; planlarımın birkaçı kelimenin tam anlamıyla worktree ve branch kurulumu göreviyle açılıyor.
5. superpowers:subagent-driven-development ya da superpowers:executing-plans yürütüyor; subagent her görevi kendi bağlam penceresinde çalıştırıyor (yeni sekmede açılır).
6. superpowers:verification-before-completion tamamlanma iddiasından önce kanıt istiyor.

Her plan, writing-plans plan şablonundan olduğu gibi gelen aynı banner’la açılıyor; yürütücü yalnızca adı geçen iki skill arasında seçim yapıyor:

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Banner’ın söylediği şu: bu planı görev görev uygulamak için iki yürütücü skill’den biri zorunlu ve adımlar onay kutusu sözdizimiyle takip ediliyor.

Bu, Claude Code’un yerleşik plan mode (yeni sekmede açılır)’undan farklı bir artefakt: plan mode tek oturuma bağlı bir araştırma aşaması; değişiklik öneriyor ama kaynak kodu düzenlemiyor. Buradaki plan dosyası ise oturumdan sonra da yaşıyor, kod gibi review ediliyor ve yeniden yürütülebiliyor.

Daha önceki Spec Kit yazımı okuyanlar kelime dağarcığını kapıda ters çevirmeli: Spec Kit’in plan.md’si mimari dokümanı, yani burada spec denen şey; tasks.md’si ise yürütülebilir döküm, yani burada plan denen şey. O yazıda ayrıca her uygulama detayını belirtmemeyi öğütlemiştim. Bu öğüt tasarım dokümanıyla ilgili; plan ise tasarım dokümanı değil: aşağıdaki fazladan uzunluk kısıtlara, kapsam dışı maddelerine, durma koşullarına, arayüzlere ve planın önceden yazdığı koda gidiyor. Bunların hiçbiri mimariyi yeniden tartışmaya açmıyor; öğüdün uyardığı şey de zaten bu. Model kademesi ve harness yazısının terimleriyle, aşağıdaki her şey harness işi: model aynı kalıyor, etrafındaki dokümanlar daha fazlasına karar veriyor.

Global Constraints#

Plan başlığı Global Constraints (planın tamamı için geçerli kısıtlar) bölümüyle açılıyor: yetkin bir ajanın önündeki koddan türetemeyeceği kurallar, çünkü bu kurallar CI’da, bir guard script’inde ya da oturumdan önce başıma gelmiş bir olayda yaşıyor. İzlediğimiz plandan:

No raw DynamoDB client imports. A CI guard (scripts/check-raw-ddb-imports.sh) rejects them outside an allowlist. All DynamoDB access goes through a dynamodb-toolbox Entity.

Yani ham DynamoDB istemcisi import etmek yasak; bir CI guard’ı bunları izin listesi dışında reddediyor ve tüm erişim dynamodb-toolbox Entity’si üzerinden geçiyor.

entityType must be set in every entity’s schema defaults. Omitting it has previously caused enforcement logic to silently no-op.

Her entity’nin şema varsayılanlarında entityType set edilmek zorunda; alan eksik kaldığında daha önce bir denetim mantığı sessizce devre dışı kalmış.

Commit after every task. Never use --no-verify.

Her görevden sonra commit; --no-verify asla.

Bu kuralların bir kısmı kalıcı kural dosyalarımla çakışıyor; o katmanı araçtan bağımsız kurulum yazısı anlatıyor. Çakışma bilinçli: plan, bu değişikliğin en çok tökezleyebileceği kuralları yeniden yazıyor; böylece kurallar karar anında yürütücünün bağlamında hazır duruyor, belki hiç yeniden açılmayacak bir dosyada beklemiyor.

Bölümün kendisi de benim icadım değil. writing-plans SKILL.md (yeni sekmede açılır) plan şablonunda Global Constraints bölümünü, onay kutusu adımlarıyla ve açık yürütücü seçimiyle birlikte taşıyor; belirsiz direktifleri de yasaklıyor. Bölüm, spec’te plana kopyalanacak proje çapında gereksinimler olduğunda ortaya çıkıyor; böyle bir gereksinim yoksa plan bölümü atlıyor. 45 planımın yalnızca 10’unda bulunması bu yüzden. İskelet depolar arasında taşınabilir; içerik yerelde kazanılıyor ve buradakilerin çoğu yaşadığım olaylardan çıktı.

Kısıtlardan biri diğerlerinin üstünde ve plan bunu tek cümleyle söylüyor:

The cache must never fail a job. Every error path falls back to the current uncached behaviour. This is the single most important constraint in this plan.

Önbellek hiçbir işi asla başarısız kılmamalı: her hata yolu mevcut önbelleksiz davranışa geri düşüyor ve plan bunu açıkça plandaki en önemli kısıt ilan ediyor. Her maddenin eşit önemde olduğu bir kısıt listesinde hiçbir madde önemli sayılmaz; o yüzden tam olarak bir kısıtı eşitlik bozucu olarak işaretliyorum. Burada bu işaret, hiçbir listenin öngöremediği durumlar için ajana bir sıralama veriyor: nefes payı ile güvenlik yarıştığında güvenlik kazanıyor ve geri düşüş yolu her zaman meşru.

File Structure#

45 planımın 26’sında File Structure (dosya yapısı) bölümü var: planın oluşturduğu ya da değiştirdiği her dosya, birer cümlelik sorumluluk açıklamasıyla bir tabloda. İzlediğimiz plan özelliği ikiye bölüyor: yalnızca saf fonksiyonlar taşıyan bir yerleşim modülü (adres anahtarından satır indeksine çevirme, blob kodlama ve çözme, matris dilimleme) ve S3 ile DynamoDB işini yapan bir orkestrasyon modülü. Tablonun altında plan, bölünmenin neden bu şekilde olduğunu söylüyor:

The pure/impure split is the load-bearing decision here. Slicing is where an index bug would be silent, and putting it in a module with no I/O means its test needs no mocks at all.

Saf/saf-olmayan ayrımı buradaki taşıyıcı karar: indeks hatasının sessiz kalacağı yer dilimleme ve dilimlemeyi I/O içermeyen bir modüle koymak, testinin hiç mock’a ihtiyaç duymaması demek.

Ağırlığı hangi kararın taşıdığını yazmak, en kolay atlanan adım. Ajana hangi çizgiyi öylece yeniden çizemeyeceğini söylüyor; review ederken de bilinçli yapıyı doğaçlama yapıdan ayırt etmemi kolaylaştırıyor. Yardımsever refactor’a heveslenen bir ajanın karşısında artık yazılı bir cümle var.

Deliberately not in this plan#

Deliberately not in this plan (bilerek bu planın dışında bırakılanlar), negatif kapsam bölümü. İzlediğimiz plan dört kapıyı kapatıyor:

• Raising MAX_OPTIMIZE_LOCATIONS above 1500.
• Raising the worker’s 2048 MB memory.
• Fixing the null → 0 coercion (separate session, already running).
• Enabling the flag in prod. That is a follow-up decision, taken on the dev numbers.

Kapatılanlar sırasıyla: konum limitini 1500’ün üzerine çıkarmak, worker belleğini 2048 MB’ın üzerine çıkarmak, null → 0 dönüşümünü düzeltmek ve flag’i prod’da açmak. İlk ikisi, bütçe daraldığında ajanın uzanabileceği kaynak düğmelerini kapatıyor. Son ikisi gerekçesini yanında taşıyor: dönüşüm düzeltmesi zaten açık tuttuğum ayrı bir oturumla çakışıyor; flag’i açmaksa dev sayılarını gördükten sonra vereceğim ayrı bir karar.

Başka bir planım, bölümün daha zor iş yaptığı yeri gösteriyor:

Any reaction to the count beyond logging it — no alarm, no threshold, no failing the job above some rate. The production rate has never been measured; this change is what makes measuring possible.

Sayıya loglamanın ötesinde her tepki kapsam dışı: alarm yok, eşik yok, belli bir oranın üstünde işi düşürmek yok; çünkü prod’daki oran hiç ölçülmemiş ve ölçmeyi mümkün kılan şey bu değişikliğin kendisi. Kendi gerekçesini savunan bir kapsam dışı maddesi bu: kimsenin gözlemlemediği bir oran üzerine alarm eşiği kurulamaz, o yüzden değişiklik gözlemi yayınlayıp orada duruyor. Yazılı gerekçe olmadığında aynı sınır ihmal gibi okunur; ya review’da konuyu yeniden açarım ya da ajan alarmı yardımseverlikle ekler.

Kapsam arızasının iki yönü de burada bitiyor: genişleme, çünkü kapı adıyla kapatılmış; sessiz daraltma, çünkü artık işin ortasında bir şeyi kesmek de aynı yazılı formu gerektiriyor.

Notes for the implementing engineer#

Notes for the implementing engineer (uygulayan mühendise notlar) izlediğimiz planda yok; aşağıdaki iki örnek başka planlarımdan geliyor. Yazma süresinin karşılığını en çok veren bölüm bu. Her not aynı anda üç şey söylüyor: risk, riskin göstereceği sinyal ve ajanın almasına izin verilen geri adım.

The single highest-risk assumption in this plan is that Order rows reliably carry routeId […] If a future refactor of route assignment stops writing this field, Task 1’s helper silently returns fewer routes (not an error) — its three tests in Task 1 are the regression guard; keep them passing.

Plandaki en riskli varsayım, Order satırlarının routeId alanını güvenilir biçimde taşıması. İleride bir refactor bu alanı yazmayı bırakırsa Task 1’in yardımcı fonksiyonu hata üretmeden daha az rota döndürüyor; Task 1’deki üç test bu gerilemenin nöbetçisi ve geçmeye devam etmeleri gerekiyor.

Değer, notun biçiminde. Not, hata üretmeyen bir kırılmayı ve onu yakalayacak artefaktı adlandırıyor. Bunu okuyan ajan, üç testin plandaki en riskli varsayımın alarm teli olduğunu ve yeşil kalmalarının görevin parçası olduğunu biliyor.

İkinci örnek, yöntemin tamamını tek cümleye sığdırıyor:

If pnpm cy:run:portal cannot drive a real WebSocket connection from Cypress in this environment, Task 4’s coverage may need to stay REST-only […] note this explicitly in the PR description rather than skipping the negative test silently.

Cypress bu ortamda gerçek bir WebSocket bağlantısı süremezse Task 4’ün kapsamı REST ile sınırlı kalabilir; ama o durumda negatif testi sessizce atlamak yerine durumu PR açıklamasına açıkça yazmak şart.

Plan geri adımı yetkilendiriyor ve aynı geri adımın sessiz sürümünü yasaklıyor. Bu duvara çarpan ajan baskı altında politika icat etmiyor; politikası hazır ve geri adımın bedeli, review’da göreceğim yerde bir cümle. Bu hamlenin review tarafındaki ikizi, review yükü yazısındaki doğrulama paketi: notun plan zamanında önceden yazdığını, paket review zamanında raporluyor.

Sessiz downgrade’i hedefleyen bölüm bu; bir oturumun bir senaryoyu kapsamsız bırakıp yeşil bitmesinin en yaygın yolu da o.

Concurrent work#

Planlar kod var olmadan, hareket etmeye devam eden bir branch’e karşı yazılıyor. Bu planın yazımı ile yürütülmesi arasında iki branch daha merge ettim; planı yeniden üretmek yerine Concurrent work — resolved (eşzamanlı işler: çözüldü) başlığı altında güncelledim:

Task 1 is implemented in adapted form (commits 7228e270 + 26509c7b): there is no -1 sentinel and no null translation.

Task 1 uyarlanmış haliyle zaten uygulanmış: -1 nöbetçi değeri de null çevirisi de artık yok; plan bunu iki commit’e işaret ederek kayda geçiriyor.

Line numbers quoted for osrm-client.ts and route-optimizer.ts predate the rebase — re-locate by symbol, not line.

İki dosya için alıntılanan satır numaraları rebase’den eski; konumu satır numarasıyla aramak yerine sembol adıyla yeniden bulmak gerekiyor.

İkinci düzeltme depomun ötesine genelleşiyor. Plandaki koordinatlar sembol adları olmalı, çünkü satır numaraları her rebase’de eskiyor ve ajan bayat numarayı hiç duraksamadan takip ediyor. osrm-client.ts içindeki retry sarmalayıcısını işaret eden plan rebase’den sağ çıkıyor; 254. satırı işaret eden plan, ajanı oraya o an ne taşındıysa ona gönderiyor.

Acceptance verification#

Acceptance verification (kabul doğrulaması), işten önce yazılmış durma koşulu. Bölüm türünü ilan ederek açılıyor:

Not a claim — a measurement.

Burası bir iddia listesi olarak yazılmamış; bir ölçüm prosedürü. Prosedür, aynı işin iki koşusu üzerinde dört log doğrulaması. İlk koşu soğuk yolu göstermek zorunda: matris inşasını ve tiling satırını. İkinci koşu newAddresses: 0 göstermeli ve tiling satırı hiç görünmemeli. Sonra tüm özelliği yanlışlanabilir kılan karşılaştırma geliyor:

Compare the two runs’ resulting total distance. They must be identical — if the cache changed a route, the sentinel translation is wrong.

If step 3 shows any difference, stop and investigate before going further. A cache that changes results is worse than no cache.

İki koşunun toplam mesafesi birebir aynı olmak zorunda; önbellek bir rotayı değiştirdiyse nöbetçi değer çevirisi yanlış demektir. Herhangi bir fark görülürse de devam etmeden durup incelemek şart, çünkü sonuçları değiştiren bir önbellek, önbelleksizlikten daha kötü.

Ajan kendi durma koşulunu yazmaz. Building to the Test makalesi (yeni sekmede açılır) eğilimi açıkça ifade ediyor: “The agent does not, on its own, validate what it ships as a user would.” Yani ajan, teslim ettiği şeyi bir kullanıcının doğrulayacağı gibi kendiliğinden doğrulamıyor. Kurulumum cevabı iki katmanda taşıyor. verification-before-completion SKILL.md (yeni sekmede açılır) genel kuralı “NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE” diye koyuyor, yani taze doğrulama kanıtı olmadan tamamlanma iddiası yok; plan ise somut kanıt listesine katkı yapıyor: hangi log satırları, hangi karşılaştırma, hangi fark görevi durduruyor. Böyle bir kontrolü hook (yeni sekmede açılır) ile durma anında mekanik olarak da çalıştırabilirsiniz; iddianın neyle sınanacağı her durumda plan metninden geliyor.

Görevlerin ortak biçimi#

Planın içinde beş görevin beşi de aynı beş adımı tekrarlıyor:

1. Başarısız olacak testi yaz.
2. Testi çalıştır, başarısız olduğunu doğrula.
3. Asgari implementasyonu yaz.
4. Testi çalıştır, geçtiğini doğrula.
5. Lint et ve commit’le.

Sıra, dokümana gömülmüş red-green-refactor (yeni sekmede açılır); yürütücünün sırayı doğaçlamamasının nedeni bu. Her görev ayrıca bir başlık bloğuyla açılıyor: Files: (oluşturulan, değiştirilen, test edilen dosyalar) ve Interfaces: (tüketilenler ve üretilenler, gerçek imzalarla). Fonksiyon imzaları, kod ortada yokken planda var.

Daha az göze çarpan plan zamanı kararı, testin ayırt etme gücü. Task 1’in fixture’ı iki matrisi tek bir düz Int32Array içine seriyor (mesafeler 0 ofsetinde, süreler n * n ofsetinde) ve her beklenen hücre gözle türetilebiliyor:

/**
 * Pure layout maths for the cached distance matrix. These tests need no mocks
 * because the module does no I/O — which is the point of the split.
 *
 * The universe is laid out on a line so every expected cell is known: the
 * distance between rows i and j is |i - j| * 100 and the duration is |i - j|.
 * A wrong index lookup therefore produces a wrong number rather than passing.
 */

const KEYS = ['a', 'b', 'c', 'd', 'e', 'f']

/** Universe of 6 points on a line: distance = |i - j| * 100, duration = |i - j|. */
function lineUniverse(): Int32Array {
  const n = KEYS.length
  const blob = new Int32Array(expectedBlobLength(n))
  for (let i = 0; i < n; i++) {
    for (let j = 0; j < n; j++) {
      blob[i * n + j] = Math.abs(i - j) * 100
      blob[n * n + i * n + j] = Math.abs(i - j)
    }
  }
  return blob
}

Baştaki yorum düzeni anlatıyor: evren bir doğru üzerine dizili, i ile j satırları arasındaki mesafe |i - j| * 100, süre |i - j|; yanlış bir indeks araması bu yüzden gözle görülür biçimde yanlış bir sayı üretiyor ve test kırmızıya düşüyor. Fixture’ın çağırdığı expectedBlobLength(n) bu kod parçasında tanımlı değil; planın Interfaces: bloğunda, kod ortada yokken bildirilmiş imzalardan biri. Yukarıdaki kod parçasını da bitmiş test dosyasından değil, plandan aldım: Task 1’in ilk adımında, önce kırmızı testi yaz talimatının altında duruyor. Düzeni anlatan docstring, anlattığı modülden önce yazılmış. Keyfî sayılarla kurulmuş bir fixture, bir kaydırılmış indeksin geçmesine izin verirdi, çünkü keyfî bir değer bir başkası kadar makul okunur. Bu fixture’da öyle bir boşluk yok: her yanlış indeks yanlış bir değer demek. Bu seçim bir plan zamanı kararı ve dilimleyiciyi yalnızca çalıştıran test ile yanlış indeksi yakalayabilen test arasındaki fark bu seçimde saklı.

Spec tarafı#

Tasarım dokümanı 188 satırlık ortalamasını kararları dondurarak hak ediyor; plan böylece hiçbir kararı yeniden tartışmıyor. Ajanla çalışırken iki bölümü öne çıkıyor.

Measured evidence (ölçülmüş kanıt) sayıları sınırlarıyla birlikte taşıyor. İzlediğimiz spec’in çözücü zamanlamaları tablosu şöyle bitiyor:

All figures measured 2026-07-30. Solver runs used a pre-built matrix pushed through the S3-pointer path, invoking the dev solver Lambda directly — the optimize-worker path itself was not exercised.

Bütün ölçümler aynı gün alınmış; çözücü koşuları önceden kurulmuş bir matrisi S3 işaretçi yolundan geçirip dev çözücü Lambda’sını doğrudan çağırmış ve optimize-worker yolunun kendisi hiç çalıştırılmamış. Ölçülmeyeni ilan etmek, sonraki okuru, ister insan ister ajan, tabloyu olduğundan geniş bir kanıt sanmaktan alıkoyuyor.

Decisions (locked) (kilitlenmiş kararlar) seçimleri, YAGNI varsayılanları dahil, donduruyor. Başka bir spec’imden:

Override flag (YAGNI default): do not persist a separate “unverified” boolean on the order.

Sipariş üzerinde ayrı bir doğrulanmamışlık boolean’ı kalıcı olarak tutulmayacak; tasarım bu alanı bilerek dışarıda bırakmış. Kilitli kayıt olmasa bu boolean, titiz bir ajanın yardımseverlikle ekleyeceği alanın ta kendisi.

Yöntemin maliyeti#

1.330 satırlık bir plan yazması pahalı ve taslağı bir skill çıkarsa bile asıl maliyet review: 1.330 satırın tamamını okuyorum. Oran, sessiz arıza modu ya da geniş etki alanı taşıyan değişikliklerde kendini ödüyor ve başka pek az yerde; bir rename önceden kayda geçirilmiş arıza modlarına ihtiyaç duymaz. Kullandığım çizgi şu: değişikliğin hata üretmeden yanlış olabileceği bir yol sayamıyorsam, plan büyük olasılıkla ek yük.

Planın kapatmaya çalıştığı boşluk, değişiklik boyutuyla da büyüyor. SpecBench (yeni sekmede açılır), ajanın gördüğü doğrulama testleri ile saklı tutulan testler arasındaki farkı ölçüyor ve kod boyutundaki her on katlık artışta bu farkın 28 puan genişlediğini raporluyor. Küçük değişikliklerde boşluk zar zor var; büyüklerde işin çoğu boşluk. Plan uzunluğu kendini bu eğri boyunca kazanıyor; tek beden bir şablonun iki yönde de ıskalamasının nedeni de bu.

Planın kendisi de yanlış olabiliyor. Kod var olmadan, hareket eden bir branch’e karşı yazılıyor; Concurrent work — resolved bölümü, bunu bir kez yaşadığım için var.

İskelet, başka depolara içerikten daha kolay geçiyor. Altı bölümün ikisi, Global Constraints ile File Structure, skill’in plan şablonundan geliyor; diğer dördü kendi eklemem ve altısı da her depoya taşınabilir. Ama alıntılanan kısıtlar, depomda belirli bir şeyi bir kez yanlış yaptığım için var. Onları olduğu gibi kopyalamak, kelimeleri olayları olmadan ithal etmek olur; Claude Code skill’lerini kopyalamanın neden işe yaramadığı sorununun yakın akrabası.

Ve bir kısıtı yazıya geçirmek onu bağlayıcı yapmıyor; kapanış hikâyesi bu.

Harfi harfine uyulan kısıt#

İzlediğimiz planın Global Constraints bölümüne kalın harflerle şunu yazmıştım:

entityType must be set in every entity’s schema defaults. Omitting it has previously caused enforcement logic to silently no-op.

Özelliği yayına aldım (#944). Üç gün sonra dört satırlık bir düzeltme merge ettim (#948) ve düzeltmenin yorumu hikâyenin tamamı:

       .item({
         pk: buildMatrixCachePK(graphVersion()),
         sk: MATRIX_CACHE_SK,
+        // Schema `.default()`s are PUT defaults — UpdateItemCommand does not
+        // apply them, and a row born without entityType fails every later
+        // GetItem at the formatting step (measured on dev, 2026-08-03).
+        entityType: 'matrix_cache',
         seq,
         rows: keys.length,
       })

Yorumun söylediği şu: şema .default()ları PUT varsayılanları, UpdateItemCommand bunları uygulamıyor ve entityType olmadan doğan satır, sonraki her GetItem çağrısında biçimlendirme adımında düşüyor (dev ortamında ölçülmüş).

Şema entityType’ı gerçekten set ediyordu; yazdığım kısıt, harfi harfine okununca yerine gelmişti. Ama yayına aldığım kod işaretçi satırını bir update ile yazıyordu ve DynamoDB Toolbox’ta anahtar olmayan bir alanda .default() bir put varsayılanı (yeni sekmede açılır): PutItemCommand uyguluyor, UpdateItemCommand uygulamıyor; update varsayılanı ayrı bir bildirim. (.key() ile işaretlenmiş bir alanda aynı çağrı anahtar varsayılanı olarak davranıyor.) Satır alan olmadan doğdu ve sonraki her okuma biçimlendirme adımında düştü. Kısıt kuralı adlandırmıştı; kuralı uygulayan mekanizma bir kat aşağıda yaşıyordu ve o katın ikinci bir kapısı vardı.

Kısıtın güçlü hali mekanizmayı adlandırır: şema varsayılanları yalnızca put’ta uygulanır, dolayısıyla her update yolu entityType’ı açıkça set etmek zorundadır. Bu ifade planlarımın hiçbirinde henüz yok. Yalnızca düzeltmenin yorumunda yaşıyor ve bu, aynı hatanın bir kat yukarısı: olay kodu eğitti, dokümanı henüz eğitmedi. Daha iyi plan yazma rehberinin bitmek zorunda olduğu yer burası, çünkü planlar da kodla aynı yoldan iyileşiyor, her seferinde bir olayla.

Kaynaklar#

• Extend Claude with skills (yeni sekmede açılır) - SKILL.md formatı: skill, gövdesi yalnızca çağrıldığında yüklenen bir Markdown talimat dosyası.
• Create custom subagents (yeni sekmede açılır) - Subagent’lar kendi bağlam penceresinde, kendi sistem prompt’u ve araç erişimiyle çalışıyor; subagent güdümlü yürütmenin modeli.
• Choose a permission mode (yeni sekmede açılır) - Claude Code’un yerleşik plan mode’u: kalıcı plan dosyasının aksine oturuma bağlı araştırma aşaması.
• Hooks reference (yeni sekmede açılır) - Sabit noktalarda shell komutu çalıştıran yaşam döngüsü hook’ları; durma koşulunu mekanik çalıştırmanın yolu.
• obra/superpowers (yeni sekmede açılır) - Baştan sona kullanılan skill seti; zincirdeki altı skill’in tamamı skills/ altında.
• superpowers: writing-plans SKILL.md (yeni sekmede açılır) - Plan şablonu: Global Constraints bölümü, onay kutusu adımları, bağımsız test edilebilir küçük görevler ve açık yürütücü seçimi.
• superpowers: verification-before-completion SKILL.md (yeni sekmede açılır) - “NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE” kuralı ve belirle, çalıştır, oku, doğrula sırası.
• github/spec-kit (yeni sekmede açılır) - GitHub’ın spec güdümlü geliştirme araç seti; plan.md’si mimari doküman, tasks.md’si yürütülebilir döküm: buradaki spec/plan adlandırmasının tersi.
• Configure Lambda function timeout (yeni sekmede açılır) - Vakanın sabit zaman bütçesinin arkasındaki 900 saniyelik (15 dakika) üst sınır.
• DynamoDB Toolbox: defaults and links (yeni sekmede açılır) - Anahtar olmayan alanlarda .default() bir put varsayılanı; .updateDefault() ayrı bir bildirim. Kapanıştaki düzeltmenin mekanizması.
• OSRM HTTP API: Table service (yeni sekmede açılır) - Tüm koordinat çiftleri için süre, annotations=duration,distance ile mesafe de döndüren /table ucu; önbelleğin ortadan kaldırdığı rota motoru çağrısı.
• SpecBench: Measuring Reward Hacking in Long-Horizon Coding Agents (yeni sekmede açılır) - Görünür doğrulama testleri ile saklı testler arasındaki farkı ölçüyor; fark kod boyutundaki her on katlık artışta 28 puan büyüyor.
• Building to the Test: Coding Agents Deliver What You Check, Not What You Requested (yeni sekmede açılır) - Ajanın kontrol edilen sinyali tatmin edip istenen davranışı doğrulamadan bıraktığı arıza moduna ad veriyor.
• Test Driven Development, Martin Fowler (yeni sekmede açılır) - Beş adımlı görev biçiminin her göreve gömdüğü red-green-refactor döngüsü.