Kural sistemleri ve davranış yönlendirmesi

Kural dosyaları, Verdent'in kodlama oturumları sırasında nasıl davrandığını ve yanıt verdiğini tanımlayan Markdown belgeleridir. Yapay zeka aracısının davranışını, çıktı biçimlendirmesini, karar alma sürecini ve proje standartlarına uyumunu yönlendirir.

Amaç: Kurallar, kodu veya ayarları değiştirmeden Verdent'in davranışını özelleştirmenize olanak tanır. Oturumlar boyunca kalıcı olan kodlama kurallarını, tercih edilen kalıpları, iletişim tarzını ve görev yürütme tercihlerini belirlerler.

Kurallar nasıl çalışır: Verdent konuşmalar sırasında kural dosyalarına sürekli başvurur ve yönergeleri kod üretimine, analize, dokümantasyona ve karar almaya uygular. Kurallar, kullanıcı tercihleriyle tutarlılığı sağlamak için her aracı yanıtını etkiler.

Üç kategori:

• Genel tercihler (VERDENT.md) - Kişisel kodlama tarzı, dil tercihleri
• Projeye özgü standartlar (AGENTS.md) - Ekip kuralları, mimari kalıplar
• Plan özelleştirmesi (Plan.md) - Plan Mode çıktı biçimi ve içeriği

Kural önceliği: Kurallar çakıştığında Verdent şu önceliği uygular: AGENTS.md (en yüksek) → VERDENT.md (orta) → varsayılanlar (en düşük)

Kullanıcı kuralları (VERDENT.md)

VERDENT.md, tüm projeler ve oturumlar genelinde geçerli olan genel tercihleri tanımlar. Kişisel kodlama tarzını, tercih edilen araçları, iletişim tercihlerini ve varsayılan davranışları belirler.

Konum ve kapsam

Dosya konumu: ~/.verdent/VERDENT.md

Kapsam: Tüm projeler için geneldir

Erişim:

• Settings → Rules → User Rules
• ~/.verdent/VERDENT.md konumunda doğrudan dosya düzenleme

Değişiklikler ne zaman etkili olur: Kurallar yeni konuşmalarda hemen uygulanır ve mevcut konuşma yanıtlarını etkiler.

Kullanım senaryoları

Biçim ve sözdizimi

VERDENT.md, madde işaretleri veya numaralı listelerle düz Markdown biçimi kullanır.

Yapı:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

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

Yazım stili:

• Açık, yönlendirici dil kullanın ("Her zaman kullan...", "Tercih et...", "Asla...")
• Başlıklarla mantıksal bölümlere ayırın
• Tek tek kurallar için madde işaretleri kullanın
• İstenen davranış hakkında spesifik olun

Geliştirici türüne göre örnekler

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

## 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

# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

Nasıl oluşturulur ve düzenlenir

Proje kuralları (AGENTS.md)

AGENTS.md, mevcut proje için aracı davranışını kontrol eden projeye özgü kuralları tanımlar. Projeye özgü ekip kodlama standartlarını, mimari kalıpları, test gereksinimlerini ve geliştirme iş akışlarını belirler.

Konum ve kapsam

Dosya konumu: Proje kök dizini

Kapsam: Yalnızca mevcut proje

Sürüm kontrolü: Ekip genelinde paylaşım için git'e işlenebilir

Erişim:

• Settings → Rules → Project Rules
• <project-root>/AGENTS.md konumunda doğrudan düzenleme

Kullanım senaryoları

Ekip iş birliği: AGENTS.md proje kökünde saklanır ve sürüm kontrolüne işlenebilir, böylece tüm ekip üyelerinin tutarlı aracı davranışıyla çalışması sağlanır.

Biçim ve sözdizimi

AGENTS.md, VERDENT.md'ye benzer şekilde yapılandırılmış bölümler ve madde işaretleriyle Markdown biçimi kullanır, ancak projeye özgü gereksinimlere odaklanır.

Yapı:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

Yazım stili:

• Buyurgan, yönlendirici dil
• İş akışı alanına göre düzenlenmiş (geliştirme, test, dağıtım)
• Spesifik komutlar ve prosedürler
• Kişisel tercihler değil, ekip genelinde standartlar

Proje türüne göre örnekler

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- 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

# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

VERDENT.md'den farkları

Kapsam:

• VERDENT.md: Tüm projeler genelinde kişisel tercihler
• AGENTS.md: Yalnızca belirli proje için ekip standartları

Öncelik:

• AGENTS.md: Daha yüksek öncelik - proje tutarlılığı için user_rules'u geçersiz kılar
• VERDENT.md: Daha düşük öncelik - hiçbir proje kuralı çakışmadığında uygulanır

İçerik odağı:

• VERDENT.md: Bireysel kodlama tarzı, iletişim tercihleri, kişisel araçlar
• AGENTS.md: Ekip kuralları, proje mimarisi, paylaşılan iş akışları, teknoloji yığını

Sürüm kontrolü:

• VERDENT.md: Paylaşılmaz - bireyin makinesinde kalır
• AGENTS.md: git'e işlenir - tüm ekiple paylaşılır

Depolama:

• VERDENT.md: ~/.verdent/VERDENT.md (genel)
• AGENTS.md: Proje kök dizini (projeye özgü)

Örnek çakışma çözümü:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

Hangisi ne zaman kullanılır:

• VERDENT.md: Tüm projeler genelinde istediğiniz kişisel tercihler
• AGENTS.md: Tüm ekibin bu proje için uyması gereken standartlar

Plan kuralları (Plan.md)

Plan.md, Plan Mode'da üretilen planların içeriğini ve biçimini özelleştirir. Plan ayrıntı düzeyini, dahil edilen bölümleri, biçimlendirme tercihlerini ve görüntülenen bilgileri kontrol eder.

Konum ve kapsam

Dosya konumu: ~/.verdent/plan_settings.json

Kapsam: Tüm projeler için geneldir

Uygulama: Yalnızca Plan Mode sırasında plan üretilirken uygulanır

Erişim:

• Settings → Rules → Plan Rules
• ~/.verdent/plan_settings.json konumunda doğrudan dosya düzenleme

Kullanım senaryoları

Biçim ve sözdizimi

Plan.md, istenen plan yapısını ve içeriğini açıklayan bölümlerle Markdown biçimi kullanır.

Yapı:

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## 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

Planlama stiline göre örnekler

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

Plan kuralları ne zaman uygulanır?

Plan kuralları uygulaması:

• Zamanlama: Yalnızca Plan Mode sırasında plan üretilirken uygulanır
• Kapsam: Kod üretimini değil, plan biçimini ve içeriğini kontrol eder
• Bağımsızlık: VERDENT.md veya AGENTS.md ile çakışmaz

Diğer kural türleri uygulaması:

• VERDENT.md: Tüm modlarda (Agent, Plan, Chat) sürekli uygulanır
• AGENTS.md: Projeye özgü davranış için tüm modlarda sürekli uygulanır

Etkileşim örneği:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

Moda özgü davranış:

• Agent Mode: VERDENT.md + AGENTS.md uygulanır (plan_rules.md yok)
• Plan Mode: VERDENT.md + AGENTS.md + Plan.md tümü uygulanır
• Chat Mode: VERDENT.md + AGENTS.md uygulanır (Plan.md yok)

Kural önceliği ve çakışma çözümü

Kurallar çakıştığında Verdent tutarlı davranış sağlamak için öncelik uygular.

Öncelik sırası

1. Proje kuralları (AGENTS.md) - En yüksek öncelik Projeye özgü kurallar genel tercihleri geçersiz kılar. Ekip standartları, tutarlılık için bireysel tercihlere göre öncelik kazanır.

2. Kullanıcı kuralları (VERDENT.md) - Orta öncelik Hiçbir projeye özgü kural çakışmadığında genel tercihler uygulanır.

3. Varsayılan davranış - En düşük öncelik Hiçbir kural belirtilmediğinde Verdent'in yerleşik varsayılanları uygulanır.

Örnek çakışma çözümü:

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

Plan kuralları: Plan.md, Plan Mode sırasında bağımsız olarak uygulanır ve kullanıcı/proje kurallarıyla çakışmaz. Plan biçimini kontrol ederken VERDENT.md ve AGENTS.md plan içindeki kod stilini kontrol eder.

Kural çakışmalarında sorun giderme

Bir kuralla çelişen beklenmedik davranış gözlemlediğinizde bu hata ayıklama stratejisini izleyin:

Adım 1: Çakışmayı belirleyin

1. Bir kuralla çelişen beklenmedik davranışı gözlemleyin
2. Duruma hangi kuralların uygulanabileceğini kontrol edin
3. Kural dosyaları arasında çelişkileri arayın

Adım 2: Kural önceliğini kontrol edin

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

Proje kuralları kişisel tercihleri geçersiz kılar.

Adım 3: İzolasyonda test edin

VERDENT.md'yi devre dışı bırakın: Dosyayı geçici olarak yeniden adlandırın veya temizleyin, çakışmanın çözülüp çözülmediğini test edin

AGENTS.md olmadan test edin: user_rules davranışını izole etmek için AGENTS.md olmadan projede çalışın

Yeni konuşma: Konuşma bağlamı etkisini ortadan kaldırmak için yeni bir oturum başlatın

Yaygın çakışma senaryoları

Senaryo 1: Biçimlendirme çakışması

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

Senaryo 2: Aynı dosyada çelişen kurallar

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

Örnek düzeltme:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

Senaryo 3: Kural çok belirsiz

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

Hata ayıklama stratejisi

1. Açık test: Verdent'e "[belirli davranış] için hangi kuralı takip ediyorsun?" diye sorun

Örnek:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

2. Kademeli iyileştirme: Belirsiz kurallara spesifiklik ekleyin

Önce:

- Use appropriate error handling

Sonra:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. Öncelik işaretleyicileri: Pazarlık edilemez kurallar için "CRITICAL:" veya "REQUIRED:" kullanın

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

Kural yazma için en iyi uygulamalar

Spesifik ve yönlendirici olun:

• Açık, buyurgan dil kullanın ("Her zaman kullan...", "Asla...", "Tercih et...")
• Belirsiz ifadelerden kaçının ("Şunu yapmaya çalış..." → "Her zaman...")
• İstemediğinizi değil, tam olarak istediğinizi belirtin

İyi:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

Kaçının:

- Try to use modern JavaScript features
- Add comments when necessary

Mantıksal olarak düzenleyin:

• İlgili kuralları bölüm başlıkları altında gruplayın
• Konuları ayırın (stil, test, dokümantasyon, güvenlik)
• Kural dosyaları genelinde tutarlı yapı kullanın

Kuralları sürdürülebilir tutun:

• Özlü kurallar yazın (madde başına bir kavram)
• Proje geliştikçe kuralları gözden geçirin ve güncelleyin
• Geçersiz kuralları derhal kaldırın

Önemli kuralları önceliklendirin:

• Kritik kuralları her bölümde önce yerleştirin
• Pazarlık edilemez standartlar için vurgu kullanın ("Kimlik bilgilerini ASLA commit etmeyin")
• Hataları veya güvenlik sorunlarını önleyen kurallara odaklanın

Kuralların etkinliğini test edin:

• Verdent'in kuralları pratikte takip ettiğini doğrulayın
• Kural uygulamasını test etmek için yeni bir konuşma başlatın
• Gerçek aracı davranışına göre kuralları iyileştirin

Ayrıntı ve esnekliği dengeleyin:

• Çok spesifik → Uyum sağlamayan katı davranış
• Çok belirsiz → Tutarsız davranış
• Bağlama uygun kararlar için alan bırakacak şekilde açık rehberlik hedefleyin

Ekip değerlendirmeleri (AGENTS.md):

• Kural oluşturmaya ekibi dahil edin
• Açık olmayan kuralların gerekçesini belgeleyin
• Ekip kurallarını kişisel tercihlere değil, paylaşılan standartlara odaklı tutun

Ayrıca bakın