Genişletilebilirlik ve özelleştirme

Neler öğreneceksiniz

Verdent for VS Code'i üç güçlü genişletilebilirlik yöntemiyle nasıl özelleştirip genişleteceğiniz: özel alt aracılar, kural sistemleri ve MCP entegrasyonu.

Genişletilebilirliğe genel bakış

Verdent for VS Code, yeteneklerini genişletmek ve davranışını özelleştirmek için üç ana yöntem sunar:

1. Özel alt aracılar - Alana özgü görevler için uzmanlaşmış yapay zeka aracıları oluşturun
2. Kural sistemi - VERDENT.md, AGENTS.md ve plan_rules.md aracılığıyla davranışı yönlendirin
3. MCP entegrasyonu - Model Context Protocol aracılığıyla harici araçları ve hizmetleri bağlayın

Her yöntem farklı özelleştirme ihtiyaçlarına hizmet eder ve kapsamlı iş akışı optimizasyonu için birleştirilebilir.

Yöntem 1: Özel alt aracılar

Genel bakış

Özel alt aracılar, kendine özel sistem istemleri, çağırma politikaları ve göreve özgü uzmanlığa sahip uzmanlaşmış yapay zeka aracılarıdır. Verdent'in yerleşik alt aracılarını (@Verifier, @Explorer, @Code-reviewer) projeye özgü yeteneklerle genişletir.

Depolama konumu: ~/.verdent/subagents/

Özel alt aracılar oluşturma

Dosya yapısı:

---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

Oluşturma yöntemleri:

Yöntem 1: Ayarlar menüsü

1. Settings → Subagents
2. "Create new subagent"
3. Ad, açıklama ve sistem istemini tanımlayın
4. Çağırma politikasını yapılandırın
5. ~/.verdent/subagents/ konumuna kaydedin

Yöntem 2: Doğrudan dosya oluşturma

1. ~/.verdent/subagents/ konumuna gidin
2. Markdown dosyası oluşturun (ör. security-reviewer.md)
3. YAML frontmatter ekleyin
4. Sistem istemini ve kullanım yönergelerini yazın

Özel alt aracılar için kullanım örnekleri

Alana özgü uzmanlık:

• Finansal hesaplamalar: Vergi uyumluluğu, finansal düzenlemeler
• Sağlık HIPAA uyumluluğu: Hasta verisi işleme standartları
• Kriptografi: Güvenlik uygulama en iyi pratikleri

Ekibe özgü iş akışları:

• Kod stili uygulayıcıları: Linter kurallarının ötesinde ekip kodlama standartları
• Dokümantasyon tutarlılığı: Belgelerin ekip şablonlarına uymasını sağlayın
• Bağımlılık denetleyicileri: Üçüncü taraf paketleri onaylanmış listelere göre izleyin

Teknoloji yığını uzmanları:

• React performans optimize edicileri: Gereksiz yeniden render'ları belirleyin
• SQL sorgu optimize edicileri: Veritabanı performansını analiz edin ve iyileştirin
• Docker yapılandırma denetleyicileri: Konteynerleştirme pratiklerini doğrulayın

Kalite güvencesi:

• Test kapsamı analizcileri: Test edilmemiş kod yollarını belirleyin
• Hata işleme denetleyicileri: Kapsamlı istisna işlemeyi sağlayın
• Günlükleme standartları uygulayıcıları: Günlükleme pratiklerini doğrulayın

Örnek: API dokümantasyon oluşturucu

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

Kullanım:

@api-documenter document the /api/users endpoints

Örnek: Veritabanı taşıma denetleyicisi

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

Çağırma politikaları

Katı politika:

• Alt aracı yalnızca @-mention ile açıkça istendiğinde çalışır
• Kullanıcı çağırma üzerinde tam kontrolü elinde tutar
• Uzmanlaşmış, ara sıra kullanılan alt aracılar için en iyisidir

Esnek politika:

• Görev kalıbı algılamasına dayalı otomatik çağırmaya olanak tanır
• Ana aracı, eşleşen görevleri otomatik olarak yönlendirir
• Sık kullanılan, iyi tanımlanmış alt aracılar için en iyisidir

Yöntem 2: Kural sistemi

Genel bakış

Kural dosyaları, Verdent'in davranışını, çıktı biçimlendirmesini ve karar vermesini kod değişikliği olmadan yönlendiren Markdown belgeleridir. Üç kural türü kapsamlı özelleştirme sağlar:

Kural önceliği

Çakışmalar olduğunda:

1. AGENTS.md (en yüksek) - Proje kuralları kullanıcı tercihlerini geçersiz kılar
2. VERDENT.md (orta) - Proje çakışması olmadığında uygulanır
3. Varsayılan davranış (en düşük) - Verdent'in yerleşik varsayılanları

Örnek çakışma:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: 4-space indentation (project rules win)

VERDENT.md (Global tercihler)

Amaç: Tüm projelerde kişisel kodlama stili ve tercihleri

Örnek:

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Erişim: Settings → Rules → User Rules

AGENTS.md (Proje kuralları)

Amaç: Ekip geneli kodlama standartları ve projeye özgü kurallar

Örnek:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

Erişim: Proje kök dizini (sürüm kontrollü)

plan_rules.md (Plan özelleştirmesi)

Amaç: Plan Mode çıktı biçimini ve ayrıntı düzeyini kontrol edin

Örnek:

# Plan Rules

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

Erişim: Settings → Rules → Plan Rules

Kural yazma en iyi pratikleri

Belirli ve yönlendirici olun:

✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"

Mantıklı şekilde düzenleyin:

• İlgili kuralları bölüm başlıkları altında gruplandırın
• Endişeleri ayırın (stil, test, dokümantasyon, güvenlik)
• Dosyalar arasında tutarlı bir yapı kullanın

Kritik kuralları önceliklendirin:

• Her bölümde önemli kuralları başa koyun
• Pazarlık edilemez standartlar için vurgu kullanın: **NEVER** commit credentials
• Hata önleme ve güvenliğe odaklanın

Etkinliği test edin:

• Kural uygulamasını doğrulamak için yeni bir konuşma başlatın
• Kuralları gerçek aracı davranışına göre iyileştirin
• Proje geliştikçe güncelleyin

Yöntem 3: MCP entegrasyonu

Genel bakış

Model Context Protocol (MCP), harici araçları, veri kaynaklarını ve hizmetleri bağlayarak Verdent'i genişletir. MCP sunucuları, Verdent ile harici sistemler arasında köprü görevi görür.

Yapılandırma: Settings → MCP Servers aracılığıyla ~/.verdent/mcp.json

MCP yetenekleri

Harici sistem erişimi:

• Veritabanı sorgu araçları (PostgreSQL, MySQL, MongoDB)
• Bulut hizmeti API'leri (AWS, Azure, GCP)
• Proje yönetimi (Jira, Linear, Asana)
• CI/CD ardışık düzenleri (Jenkins, GitHub Actions)
• İzleme hizmetleri (Datadog, New Relic)

Özel araç geliştirme: Tescilli sistemler için MCP sunucuları oluşturun:

• Dahili API entegrasyonları
• Eski sistem köprüleri
• Uzmanlaşmış veri kaynakları
• İş akışı otomasyon araçları

MCP ile özel alt aracılar ile kurallar karşılaştırması

Örnek: Üç yöntemi de birleştirme

Senaryo: Katı uyumluluk gereksinimleri olan tam yığın geliştirme ekibi

Özel alt aracı:

---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]

AGENTS.md (Proje kuralları):

## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access

MCP entegrasyonu:

• Uyumluluk veritabanı MCP sunucusu: İşlemleri uyumluluk kurallarına göre denetleyin
• Denetim günlüğü MCP sunucusu: Tüm hassas veri erişimlerini kaydedin

İş akışı:

User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint

Genişletilebilirlik en iyi pratikleri

Basit başlayın, ölçeklendirin

Kademeli benimseme:

1. Aşama 1: Temel kurallarla başlayın (VERDENT.md veya AGENTS.md)
2. Aşama 2: Tekrarlanan uzmanlaşmış görevler için özel alt aracılar ekleyin
3. Aşama 3: Harici sistem bağlantıları için MCP'yi entegre edin

Yöntemleri stratejik olarak birleştirin

Sinerji örnekleri:

Kurallar + alt aracılar:

• AGENTS.md özel alt aracıların ne zaman çağrılacağını belirtir
• Kurallar, alt aracı önerilerinin takip edilmesini zorunlu kılar

Kurallar + MCP:

• AGENTS.md hangi MCP sunucularının kullanım için onaylandığını tanımlar
• Kurallar harici veri erişiminin ne zaman gerektiğini belirtir

Alt aracılar + MCP:

• Özel alt aracı, harici sistemlere erişmek için MCP araçlarını kullanır
• Alt aracı, MCP sonuçlarını uzmanlaşmış uzmanlıkla yorumlar

Özelleştirmeleri belgeleyin

Ekip dokümantasyonu: Özel alt aracılar ve proje kuralları (AGENTS.md) için:

• Belirgin olmayan kuralların veya alt aracıların gerekçesini belgeleyin
• Doğru kullanım örnekleri sunun
• Sorun giderme kılavuzları ekleyin
• Kodla birlikte sürüm kontrolü altına alın

Kişisel dokümantasyon: VERDENT.md ve kişisel alt aracılar için:

• Karmaşık kuralları gerekçeyle açıklayın
• Kuralları düzenli ve güncel tutun
• Eskimiş kuralları hemen kaldırın

Kapsamlı test edin

Doğrulama süreci:

1. Özelleştirmeyi oluşturun (alt aracı/kural/MCP yapılandırması)
2. Test etmek için yeni bir konuşma başlatın
3. Davranışın beklentilerle eşleştiğini doğrulayın
4. Sonuçlara göre iyileştirin
5. Başarılı kalıpları belgeleyin

Yaygın test senaryoları:

• Alt aracı beklendiğinde otomatik olarak çağrılıyor mu?
• Proje kuralları kullanıcı kurallarını doğru şekilde geçersiz kılıyor mu?
• MCP sunucusu bağlanıp işlemleri yürütüyor mu?
• Birleştirilmiş yöntemler çakışma olmadan etkileşime giriyor mu?

Genişletilebilirlik sorunlarını giderme

Özel alt aracı sorunları

Alt aracı çağrılmıyor:

• Çağırma politikasını kontrol edin (katı, açık @-mention gerektirir)
• "When to use" yönergelerinin isteğinizle eşleştiğini doğrulayın
• Dosyanın ~/.verdent/subagents/ dizininde olduğundan emin olun
• YAML frontmatter söz dizimini kontrol edin

Beklenmeyen alt aracı davranışı:

• Netlik için sistem istemini gözden geçirin
• "When to use" ve "When NOT to use" yönergelerini iyileştirin
• Davranışı izole etmek için açık @-mention ile test edin
• Sonuçlara göre sistem istemini yineleyin

Kural çakışmaları

Kural uygulanmıyor:

• Kural önceliğini kontrol edin (AGENTS.md > VERDENT.md)
• Dosyanın doğru konumda olduğunu doğrulayın
• Temiz bir uygulama testi için yeni bir konuşma başlatın
• Kuralları daha belirli ve yönlendirici hale getirin

Beklenmeyen davranış:

• Aynı dosyada çelişen kurallar arayın
• Kuralların çok belirsiz olup olmadığını kontrol edin
• Doğru kural dosyasının düzenlendiğini doğrulayın
• Açık dil kullanın ("Always", "Never", "Prefer")

MCP entegrasyonu sorunları

Bağlantı hataları:

• mcp.json söz dizimini doğrulayın
• Kimlik doğrulama bilgilerini kontrol edin
• MCP sunucusunun çalıştığından ve erişilebilir olduğundan emin olun
• Ağ bağlantısını doğrulayın

Araç çağırma sorunları:

• MCP sunucusunun beklenen araçları sunduğunu onaylayın
• Araç parametre biçimlerini kontrol edin
• Hatalar için MCP sunucu günlüklerini inceleyin
• MCP sunucusunu bağımsız olarak test edin

Ayrıca bakınız