@sabrialperenkaya/ai-context

Bir projeye skill, domain context ve harici araç entegrasyonu kurar; sonra bunları o projenin kullandığı her AI kodlama aracı için otomatik yapılandırır.

English README →

npx @sabrialperenkaya/ai-context

Sihirbaz açılır: skill'leri, context'leri, entegrasyonları ve araçları seç, bitti.

Yayınlanmamış main dalını denemek istersen npm doğrudan repodan da kurabilir — prepare script'i derlemeyi kendisi yapar:

npx github:lordgrimx/ai-context

Hangi problemi çözüyor

Bir agent senin repona ilk kez girdiğinde projeyi hiç tanımıyor. Mimariyi rastgele açtığı dosyalardan çıkarmaya çalışıyor, convention'ları tahmin ediyor, zaten var olan şeyleri yeniden yazıyor ve bir ekranı düzeltirken ortak bir component'i paylaşan başka bir ekranı bozuyor.

Genel çözüm: kimsenin güncellemediği uzun bir CLAUDE.md, sonra ikinci araç için kopyalanmış hâli, sonra üçüncüsü.

Bu proje o içeriği yönetilen bir artifact hâline getiriyor: bir kez yazılıyor, sürümleniyor, projeye kuruluyor ve tek bir kaynaktan her aracın kendi formatına dönüştürülüyor.

Bu bir dosya kopyalayıcı değil. Dosya kopyalamak sürecin son adımı, amacı değil.

Dört kavram

| | Nedir | Örnek | |---|---|---| | Skill | Tek bir yeniden kullanılabilir yetenek. Projeden bağımsız. | coach — kod yazmadan önce kararı ortaya koy | | Context manager | Bir alanda çalışmak için gereken her şey: mimari, kararlar, kurallar, workflow'lar, doğrulama | frontend-developer | | Integration | Projede kurulu harici bir araçtan nasıl faydalanılacağı | codegraph, ponytail | | Adapter | Bir AI aracının nasıl yapılandırılmak istediği | claude-code, codex, cursor, gemini-cli |

Skill agent'ın nasıl davranacağını her yerde belirler. Context burada neyi bilmesi gerektiğini. Integration neyi başka bir araca devredebileceğini. Adapter ise sadece teslimat katmanı.

Projene ne kurulur

.ai-context/                       kanonik içerik — tek kopya, araçtan bağımsız
├── manifest.json                  ne kurulu, nereye, hangi sürümde
├── skills/coach/SKILL.md
├── integrations/<id>/INTEGRATION.md
└── contexts/frontend-developer/
    ├── context.md                 giriş noktası
    ├── architecture/              sistem nasıl çalışıyor      ← sen doldur
    ├── decisions/                 neden böyle çalışıyor       ← sen doldur
    ├── rules/                     kesin kurallar
    ├── workflows/                 iş sırası, impact analysis
    └── verification/              bir şeyi bozmadığını nasıl kanıtlarsın ← düzenle

.claude/skills/…    CLAUDE.md    AGENTS.md    .cursor/rules/…    GEMINI.md

Araç dosyaları .ai-context/ içine işaret eden ince yönlendiricilerdir. Gövdeler tek yerde durur; beşinci bir araç eklemek hiçbir şeyi çoğaltmaz ve düzenlenecek tek bir yer olur.

AGENTS.md gibi ortak dosyalarda sadece <!-- ai-context:start --> işaretleri arasındaki bölge değiştirilir — kendi yazdıkların korunur.

Entegrasyonlar

Şu an ikisi geliyor:

CodeGraph — MCP üzerinden çalışan, önceden indekslenmiş bir kod bilgi grafiği. "Bunu gerçekten ne kullanıyor?" sorusunu tek çağrıda cevaplıyor. Impact analysis'in tamamen bu soruya dayandığını ve grep'in bu soruyu kötü cevapladığını düşünürsek — re-export, alias'lı import ve dinamik erişimi kaçırır — en yüksek getirili araç bu.

npm i -g @colbymchenry/codegraph && codegraph install && codegraph init

Ponytail — agent'ı "tembel senior developer" karar merdivenine tabi tutan, çalışan en az kodu yazdıran bir plugin.

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Bunları nasıl kuruyorsun

Bir entegrasyon seçtiğinde şunlar yazılır: agent'ın aracı iyi kullanabilmesi için gereken rehber (ne zaman güvenilmemesi gerektiği dâhil) ve üreticinin kendi komutlarını içeren, üretilmiş bir setup.sh / setup.ps1.

Kurulum sırasında hiçbir şey çalıştırılmaz. Aracı gerçekten kurmak için:

npx aictx setup codegraph          # tüm komutları gösterir, onay ister, çalıştırır
sh .ai-context/integrations/codegraph/setup.sh   # ya da script'i kendin çalıştır

İki sınır bilinçli. Sadece shell adımları otomatikleştirilir — Ponytail'in /plugin install komutu terminale değil, AI aracının içine yazılır; script onu çalıştırıyormuş gibi yapmak yerine ekrana basar. Ve script'ler uzaktaki bir kurulumu shell'e pipe etmez; üretici ikisini de sunuyorsa paket yöneticisi komutu kullanılır. Senin reponun içine üretilen bir dosya, kimsenin incelemediği kodu indirip çalıştırmamalı.

Tespit salt-okunur ve proje düzeyindedir; "bulunamadı" demek "burada işaret yok" demektir, "kurulu değil" demek değil.

Workflow'lar bir yeteneğe (code-search) bağlıdır, bir ürüne değil. O yeteneği sağlayan bir araç kurulu değilse workflow'daki manuel prosedür geçerli kalır; kuruluysa onun yerine araç kullanılır. Gelecekteki entegrasyonların hiçbir şey değiştirmeden devreye girebilmesinin sebebi bu.

Bir entegrasyon kurulu bir skill ile çakışıyorsa, hangisinin kazandığını kendi dokümanı söyler. Ponytail ne kadar kod yazılacağının sahibi; coach ise kararı ortaya koyup açıklamanın. Aynı şeyi tekrar eden iki otorite, ikisinin de göz ardı edilmesiyle sonuçlanır.

İki kez çalıştırmak güvenli

Yazılan her dosyanın hash'i manifest'te tutulur.

• dosya değişmemişse → sessizce atlanır
• kaynak değişmiş ve sen dokunmamışsan → güncellenir
• sen düzenlediysen → sorulmadan asla üzerine yazılmaz (--force ile zorlanır)
• artık seçiminde yoksa → silinir, sen düzenlemediysen

install mevcut kurulumun üstüne ekler, değiştirmez.

Komutlar

npx @sabrialperenkaya/ai-context                 # sihirbaz
npx aictx install --context frontend-developer --integration codegraph --target claude-code
npx aictx update                                 # güncel sürümlerle yeniden üret
npx aictx update --dry-run                       # önizle, hiçbir şey yazma
npx aictx setup codegraph                        # kurulum komutlarını onay alarak çalıştır
npx aictx remove coach --target cursor
npx aictx list                                   # katalog + bu projede ne var
npx aictx docs                                   # docs-sync/index.html + kapsam raporu
npx aictx docs --check                           # dokümantasyon bayatsa hata ver

Bayraklar: --skill, --context, --integration, --target (tekrarlanabilir), --cwd, --force, --dry-run, --verbose, --yes.

Kurulumdan sonra

architecture/ ve decisions/ şablon olarak gelir — CLI senin projeni bilemez ve kendinden emin şekilde yanlış bir mimari dosyası, hiç olmamasından kötüdür.

En hızlı yol: bir agent'ı repoya yönlendirip iki dosyayı taslak olarak yazdırmak, sonra yanlışlarını düzeltmek. Taslağı gözden geçirmek sıfırdan yazmaktan çok daha ucuz ve asıl değerli kısım düzeltmeler. CodeGraph kuruluysa bu taslak belirgin şekilde daha iyi çıkar, çünkü agent tahmin etmek yerine keşfedebilir.

.ai-context/ klasörünü commit'le — amaç zaten bu. Değişikliklerini kod gibi gözden geçir.

Genişletme

| Ne yapmak istiyorsun | Oku | |---|---| | Skill ekle | docs/skill-development.md | | Context manager ekle | docs/context-development.md | | Harici araç entegrasyonu ekle | docs/integration-development.md | | Yeni AI aracı ekle | docs/adapter-development.md | | install / update / remove nasıl çalışıyor | docs/installation.md | | Kodu belgele (/docs-sync) | docs/documentation-system.md |

Türkçeleri: docs/tr/ — aynı dokümanların Türkçe karşılıkları.

Skill, context ve integration'lar klasörlerden keşfedilir — kayıt edilecek merkezî bir liste yoktur. Sadece adapter'ların listesi vardır, çünkü sihirbazın bir gösterim sırasına ihtiyacı var.

content/ altındaki içerik (skill'ler, context'ler, entegrasyon dokümanları) bilinçli olarak İngilizce: onları okuyan insan değil AI agent'ı ve bu araçlar İngilizce talimatları belirgin şekilde daha isabetli uyguluyor. Bir kuralı çevirmek, uygulanma olasılığını düşürmek demek.

Depo yapısı

content/            veri: kurulan içerik
├── skills/<id>/
├── contexts/<id>/
└── integrations/<id>/

src/core/           registry, plan, installer, manifest, tespit — hiçbir AI aracını bilmez
src/adapters/       araç başına bir dosya — sadece kendi aracını bilir
src/cli/            sihirbaz ve komutlar — dosya formatlarını bilmez
docs/               yukarıdakilerin her birinin nasıl genişletileceği
test/               node:test

Bağımlılık yönü tek taraflı: cli → core → (types) ve adapters → core/types. Core hiçbir adapter'ın detayını import etmez, dolayısıyla yeni bir araç eklemek kurulumu bozamaz.

Geliştirme

npm install
npm run build       # tsc → dist/
npm test            # node:test, test framework bağımlılığı yok
npm run typecheck
npm run dev -- list # CLI'ı kaynaktan çalıştır

Node 20.11+. Tek runtime bağımlılığı: @clack/prompts (sihirbaz için).

Bir değişikliği uçtan uca denemek için:

node dist/cli/index.js install --context frontend-developer --target claude-code --cwd /tmp/deneme --yes

Sürüm çıkarma

npm ve GitHub'ı senkron tutan şey npm version: package.json'ı yükseltir, commit atar ve aynı isimde bir git tag'i oluşturur — hepsi tek adımda.

npm test && npm run build
npm version patch        # ya da minor / major — commit + tag
git push --follow-tags
npm publish

Önce push, sonra publish — böylece npm'de var olan her sürüm GitHub'da da vardır. prepare script'i hem yayında hem git kurulumunda dist/'i yeniden derler, yani unutulacak ayrı bir build adımı yok.

Tasarım kararları

Buraya yazıldılar çünkü en çok yeniden tartışılacak olanlar bunlar:

Kanonik içerik + ince yönlendiriciler, araç başına kopya değil. N kopya zamanla birbirinden ayrışır. Tek kopya + beş adet 10 satırlık stub ayrışmaz ve .ai-context/ tek doğruluk kaynağı olarak kalır.

Timestamp değil, manifest hash'i. Timestamp bir dosyanın değiştiğini söyler; hash bizim yazdığımızdan farklı mı olduğunu söyler — "kaynak güncellendi" ile "kullanıcı düzenledi" ayrımını yapan tek soru bu.

Entegrasyon kurmak dosya yazar; çalıştırmak ayrı bir adımdır. Sihirbazda bir kutu işaretlemek, makineyi değiştirmeye verilen onay değildir; bu yüzden aictx setup her komutu gösterip önce onay ister. Üretilen script'ler uzaktaki bir kurulumu asla shell'e pipe etmez.

Workflow'lar ürüne değil yeteneğe bağlıdır. Gelecekte başka bir kod indeksi CodeGraph'in yerini hiçbir workflow düzenlenmeden alabilir.

Silme = daha küçük bir seçimle kurulum. Ayrı bir silme mantığı olmadığı için senkronizasyondan çıkabilecek ikinci bir kod yolu da yok.

Adapter'lar saf fonksiyondur. Saat yok, dosya sistemi yok. Saf olmayan bir adapter her çalıştırmada tüm dosyaları düzenlenmiş gibi gösterirdi.

Klasör tabanlı keşif. Merkezî bir skill listesi, birinin güncellemeyi unutacağı bir listedir.

Teşekkür

Entegrasyonlar, kendi yazarlarına ait üçüncü taraf araçları anlatır: CodeGraph — Colby McHenry ve Ponytail — Dietrich Gebert, ikisi de MIT lisanslı. Bu proje onların kodunu değil, kullanım rehberini içerir.

Lisans

MIT