İlkeler, kısıtlamalar ve standartlarla bir anayasa oluşturma

  • 10 dakika

Anayasa, GitHub Spec Kit ile belirtim temelli geliştirmenin temelini oluşturur. Bu ünitede kurumsal geliştirme senaryoları için etkili anayasaların nasıl oluşturulacağı araştırilmektedir.

Anayasanın temellerini gözden geçirme

Anayasa dosyası, projenizi yöneten, tartışılamayan ilkeleri, kısıtlamaları ve standartları yakalar. Ayrıca yapay zeka destekli geliştirme için koruma görevi de görür. Aracı belirtimler, planlar, görevler veya kod oluşturduğunda, önerilerin standartlarınıza uygun olduğunu doğrulamak için kural setine başvurur.

İyi tanımlanmış bir anayasanın başlıca avantajları şunlardır:

  • Tutarlılık zorlaması: Uzun projeler ve birden çok geliştirici arasında mimari kararlarla uyumun sağlanması.
  • Uyumluluk belgeleri: Mevzuat gereksinimlerini ve güvenlik ilkelerini açık ve denetlenebilir hale getirir.
  • Kurumsal bilgi yakalama: Zor kazanılan dersleri yapay zeka kodu oluşturmada yol gösteren bir biçimde korur.
  • Azaltılmış bilişsel yük: Geliştirme sırasında kuruluş ilkelerinin uygulanmasını otomatikleştirir.

Anayasanın amacı

İyi tanımlanmış bir anayasanın avantajları, otomatik uygulama yoluyla uygulamada güçlü hale gelir. Anayasa "Tüm duran veriler şifrelenmelidir" diyorsa, yapay zeka aracısı dosyaları düz metin olarak depolamayı önermez; şifrelemeyi tasarımlarına otomatik olarak ekler. Dosya yüklemeleri için bir belirtim oluşturduğunuzda, plan Azure Depolama şifreleme yapılandırmasını içerir. Kodu oluşturduğunuzda, uygulamanız şifrelenmiş depolama hizmetlerini kullanır.

Her avantajın gerçek geliştirme senaryolarında nasıl ortaya çıkar olduğunu göz önünde bulundurun:

  • Tutarlılığın sağlanması: Aylarca süren veya birden fazla geliştiricinin yer aldığı projeler, mimari kararlardan uzaklaşabilir. Bir geliştirici anayasa olmadan yerel dosya depolamayı kullanırken, diğer geliştirici de benzer özellikler için Azure Blob Depolama'yı kullanabilir. Anayasa, yapay zeka yardımcılarının her zaman başvurdığı standartları kodlayarak bu kaymayı önleyerek tüm özelliklerde tek tip teknoloji seçimleri yapılmasını sağlar.

  • Uyumluluk belgeleri: Mevzuat gereksinimleri, güvenlik ilkeleri ve iç idare kurallarına uyulmalıdır. Anayasa, gereksinimleri açıkça ortaya koyarak uyumluluğu nasıl uyguladığınıza ilişkin denetlenebilir bir kayıt oluşturur. Denetçi "Kişisel verilerin günlüğe kaydedilmediğinden nasıl emin olabilirsiniz?" sorusunu sorduğunda, anayasa gereksinimine işaret eder ve oluşturulan tüm kodların bu kısıtlamaya uygun olduğunu gösterirsiniz.

  • Kurumsal bilgi yakalama: Deneyimli mimarlar ve güvenlik ekipleri, belirli API desenlerinin performans sorunlarına neden olduğunu veya belirli kimlik doğrulama akışlarının güvenlik açıkları oluşturduğunu keşfetmek gibi zor kazanılan derslere dayalı kararlar alır. Anayasa bu bilgeliği yapay zeka kodu oluşturmaya yol gösteren bir biçimde koruyarak yeni ekip üyelerinin aynı kısıtlamaları tekrar tekrar yeniden bulmasını engelliyor.

  • Azaltılmış bilişsel yük: Geliştiricilerin yapay zeka isterken her kuruluş standardını hatırlaması gerekmez. Anayasa, "Gizli diziler için Azure Key Vault kullanma" veya "Microsoft Entra Kimliği aracılığıyla kimlik doğrulaması" gibi ilkelerin uygulanmasını otomatikleştirir. Yapay zeka, oluşturulan her planı gereksinimlerin denetim listesine göre el ile denetlemek yerine bunları otomatik olarak birleştirir.

Kurumsal geliştirme ortamlarında, anayasalar genellikle şunları kodlar:

  • Şirket ilkeleri tarafından zorunlu kılınan güvenlik gereksinimleri.
  • Kurumsal iş yükleri için performans ve ölçeklenebilirlik hedefleri.
  • Azure hizmetleri ve iç araçlarla uyumlu teknoloji seçenekleri.
  • Mühendislik en iyi uygulamalarından kodlama standartları ve mimari desenleri.
  • Erişilebilirlik standartları, kişisel veri koruma ve denetim gereksinimleri gibi uyumluluk yükümlülükleri.

Etkili bir anayasanın yapısı

İyi yapılandırılmış bir anayasa, ilkeleri yapay zeka yardımcılarının kolayca başvurabileceği kategoriler halinde düzenler.

Yaygın bölümler şunlardır:

  • Teknoloji standartları.
  • Güvenlik gereksinimleri.
  • Performans ve ölçeklenebilirlik.
  • Kodlama standartları.
  • Uyumluluk ve idare.

Aşağıdaki bölümlerde her kategorinin etkili bir şekilde nasıl tanımlanacağı gösterilmektedir.

Teknoloji standartları

Teknoloji standartları onaylı teknolojileri, platformları ve çerçeveleri belirtmek için kullanılır.

Örneğin, aşağıdaki bölümde arka uç geliştirme için Azure hizmetleri ve .NET zorunlu kılınıyor:

## Technology Standards

- All cloud resources must be hosted on Microsoft Azure.
- Back-end services use .NET 8 or later.
- Front-end applications use React or Blazor.
- Database: Azure SQL Database or Cosmos DB (no on-premises SQL Server).
- Secret management exclusively via Azure Key Vault.

Bu kısıtlamalar yapay zekanın uyumsuz teknolojiler önermesini engeller. Anayasada Azure zorunlu kılınıyorsa GitHub Copilot, Amazon Web Services Lambda işlevlerini önermez.

Güvenlik gereksinimleri

Kimlik doğrulaması, yetkilendirme, şifreleme ve veri koruma kuralları gibi öğeleri tanımlamak için güvenlik gereksinimleri kullanılabilir.

Örneğin, aşağıdaki bölümde bir iç uygulama için güvenlik ilkeleri oluşturulur:

## Security Requirements

- Authenticate all API requests using Microsoft Entra ID tokens.
- Encrypt all data at rest using AES-256 encryption.
- Encrypt data in transit using TLS 1.2 or higher.
- Never log personally identifiable information (PII).
- Store no secrets in source code or configuration files.
- Implement role-based access control (RBAC) for all features.

Güvenlik ilkeleri kurumsal geliştirme için kritik öneme sahiptir. Açık gereksinimler, oluşturulan kodun başlangıçtan itibaren güvenliği içermesini sağlar.

Performans ve Ölçeklenebilirlik   

Performans ve ölçeklenebilirlik gereksinimleri, yük altındaki sistem davranışına yönelik beklentileri ayarlamak için kullanılır.

Örneğin, aşağıdaki bölüm bir API için performans hedeflerini tanımlar:

## Performance and Scalability

- APIs must respond within 200ms for 95th percentile requests.
- System must handle 10,000 concurrent users.
- Use asynchronous processing for operations exceeding 5 seconds.
- Implement caching for frequently accessed data.
- Design for horizontal scalability using Azure App Service or Container Apps.

Performans gereksinimleri mimari kararlara yol gösterir. Anayasa büyük dosya yüklemelerinin zaman uyumsuz olarak işlenmesini gerektiriyorsa, plan arka plan işlemeyi içerir.

Kod standartları ve yönergeleri

Standartlar ve yönergeler, kod kalitesini sağlamaya yardımcı olan gereksinimler sağlar.

Örneğin, aşağıdaki bölümde bir .NET projesi için kodlama kuralları özetlenmiştir:

## Coding Standards

- Follow Microsoft C# Coding Conventions.
- Maintain minimum 80% unit test coverage.
- All public APIs documented with XML comments.
- Use dependency injection for service dependencies.
- Implement structured logging using ILogger interface.

Kodlama standartları, kod tabanı genelinde tutarlılık sağlar. Yapay zeka tarafından oluşturulan kod, anayasa bunlara başvurduğunda takım kurallarıyla uyumlu hale gelir.

Uyumluluk ve idare

Uyumluluk ve idare gereksinimleri, mevzuat ve iç ilke gereksinimlerini belge etmek için kullanılır.

Örneğin, aşağıdaki bölüm veri işleme için uyumluluk ilkelerini yakalar:

## Compliance and Governance

- Comply with local and international standards that protect personal information for all user data processing.
- Implement audit logging for all data modifications.
- Support accessibility standards (WCAG 2.1 Level AA).
- Enable monitoring and alerting via Azure Application Insights.
- Retain logs for minimum 90 days for compliance audits.

Uyumluluk ilkeleri, kuruluşunuzu mevzuat ihlallerine karşı korur. Anayasa, bu ilkelerin gelişim sırasında unutulmamasını sağlar.

GitHub Spec Kit ile anayasa oluşturma

GitHub Spec Kit'in /speckit.constitution komutu, bir anayasa dosyası oluşturmak veya güncelleştirmek için kullanılabilir.

Mevcut projeler

Zaten bir anayasa dosyası içeren mevcut bir proje üzerinde çalışırken komutunu kullanarak anayasayı /speckit.constitution güncelleştirebilirsiniz. GitHub Copilot mevcut anayasayı inceler ve kod tabanınıza göre güncelleştirmeler önerir. GitHub Spec Kit'in kendisinde yapılan güncelleştirmeler de önerilen değişikliklere yansıtılabilir.

Henüz bir anayasası olmayan mevcut bir projeye GitHub Spec Kit eklerken, GitHub Copilot Chat'teki komutunu kullanarak /speckit.constitution bir tane oluşturabilirsiniz. GitHub Copilot, mevcut kod tabanını inceler ve proje ilkelerini ve kısıtlamalarını çıkararak bir ilk constitution.md dosya oluşturur. Gerekirse, oluşturulan anayasayı geliştirerek projenizin gereksinimlerini doğru şekilde yansıtmasını sağlayabilirsiniz.

Yeni projeler

GitHub Spec Kit'i kullanarak yeni bir projeye başlarken, GitHub Copilot Chat'teki komutu kullanarak /speckit.constitution sıfırdan bir anayasa oluşturabilirsiniz.

Yeni bir projenin anayasasını oluşturmak için:

  1. Projenizi Visual Studio Code'da açın ve GitHub Spec Kit'in başlatıldığından emin olun.

  2. GitHub Copilot Sohbeti'ni /speckit.constitution açın ve ardından komutunu proje ilkelerinizin ve kısıtlamalarınızın doğal dil açıklamasıyla çalıştırın.

    Örneğin, aşağıdaki istemi sağlayabilirsiniz:

    /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.

    GitHub Copilot, kategorilere göre düzenlenmiş bölümler içeren yapılandırılmış constitution.md bir dosya oluşturur.

Oluşturulan anayasayı iyileştirme

GitHub Copilot ilk anayasayı oluşturduktan sonra, doğruluğu sağlamak için bu anayasayı gözden geçirin ve düzenleyin.

Aşağıdaki adımları göz önünde bulundurun:

  • Eksik ilkeleri ekleme: GitHub Copilot önemli gereksinimleri atlarsa bunları el ile ekleyin. Örneğin, kuruluşunuz belirli günlük biçimleri gerektiriyorsa bu kısıtlamayı ekleyin.

  • Gereksiz içeriği kaldırma: GitHub Copilot, şablon veya aşırı genel ilkeler oluşturabilir. Somut rehberlik sağlamayan her şeyi silin.

  • İlkeleri belirli ve test edilebilir hale getirin: Belirsiz deyimleri ölçülebilir ölçütlerle değiştirin. "Sistem hızlı olmalıdır" ifadesini "API yanıtları 95% istek için 200 ms içinde tamamlandı" olarak değiştirin.

  • İç standartlarla uyumlu hale getirme: Mümkün olduğunda mevcut belgelere başvurun. Örneğin: "API tasarımı için Mühendislik Mükemmelliği yönergeleri v2.3'e uyun."

  • Paydaşlarla doğrulama: Gerekli tüm gereksinimleri yakaladığını onaylamak için anayasayı güvenlik, uyumluluk ve mimari ekipleriyle paylaşın.

Anayasa canlı bir belgedir, ancak çok seyrek değişir. Oluşturulduktan sonra özellik geliştirme sürecinde kararlı rehberlik sağlar.

Belirtim temelli geliştirme iş akışında anayasa

Siz sözleşmeyi/kuralları oluşturduktan sonra, GitHub Spec Kit sonraki iş akışı aşamalarında otomatik olarak ona başvurur.

  • Belirtim aşaması: Özellik belirtimleri oluşturmak için çalıştırdığınızda /speckit.specify GitHub Copilot, gereksinimlerin belirlenmiş ilkeleri ihlal etmediğinden emin olmak için anayasayı denetler. Belirtim dosyaları yerel olarak depolamayı önerirse GitHub Copilot bu çakışmayı anayasanın Azure Blob Depolama yetkisiyle işaretlemektedir.

  • Planlama aşaması: Komut, /speckit.plan anayasa gereksinimleriyle uyumluluğu açıkça doğrulayan teknik planlar oluşturur. Plan, tasarımın ilgili her ilkeyi nasıl karşılayanı gösteren bölümler içerir.

  • Analiz aşaması: Çalıştırma /speckit.analyze , belirtimlerinizi, planınızı ve görevlerinizi anayasayla karşılaştırır ve tutarsızlıkları belirler. Örneğin, görevler kullanıcı adı/parola kimlik doğrulaması uygulamayı içeriyorsa ancak anayasa Microsoft Entra Id gerektiriyorsa analiz bu sapması yakalar.

  • Uygulama aşaması: ile /speckit.implementkod oluşturduğunuzda GitHub Copilot, anayasa kısıtlamalarına uygun uygulamalar üretir. Kod, anayasa tarafından zorunlu kılınırsa Microsoft Entra Id kimlik doğrulamasını otomatik olarak içerir.

Bu tümleştirme, anayasanın bu kadar güçlü olmasının nedenidir; ilkeler bir kez yazılır ve yapay zeka bunları geliştirme boyunca otomatik olarak uygular.

Kuruluşa özgü anayasa konuları

Kurumsal iç projeler için anayasa oluştururken şu ortak gereksinimleri dahil edin:

  • Azure öncelikli mimari: Barındırma, depolama, veritabanları ve destekleyici altyapı için Azure hizmetlerini zorunlu kılın. Bu gereksinim, kurumsal bulut stratejisi ve kullanılabilir araçlarla uyumlu hale getirildi.

  • Kurumsal kimlik doğrulaması: Kimlik doğrulaması için Microsoft Entra Id ve yetkilendirme için RBAC gerektir. Çoğu kurumsal iç uygulama, kurumsal kimlik sistemleriyle tümleşir.

  • Güvenlik ve uyumluluk: Kurumsal güvenlik ilkelerine, Güvenilir Bilgi İşlem ilkelerine ve geçerli uyumluluk çerçevelerine başvurun.

  • İzleme ve gözlemlenebilirlik: Azure Application Insights'ı veya eşdeğer izleme çözümlerini zorunlu kılın. Kurumsal uygulamaların üretim desteği için kapsamlı telemetriye ihtiyacı vardır.

  • Geliştirici araç standartları: Onaylanan çerçeveleri, kitaplıkları ve geliştirme uygulamalarını belirtin. Örneğin, iç akışlardan onaylanan NuGet paketlerinin kullanılmasını zorunlu kılar.

  • Erişilebilirlik: WCAG 2.1 Düzey AA uyumluluk gereksinimlerini ekleyin. Kurumsal iç araçların engelli çalışanlar tarafından erişilebilir olması gerekir.

Örnek kurumsal iç anayasa parçacığı:

# Employee Portal Constitution

## Azure Platform Standards
- Host all services on Azure App Service or Azure Container Apps.
- Use Azure Blob Storage for document storage.
- Database: Azure SQL Database or Cosmos DB.
- Secrets stored exclusively in Azure Key Vault.
- Use Azure Front Door for global distribution.

## Identity Integration
- Authenticate via Microsoft Entra ID using OAuth 2.0 / OpenID Connect.
- Implement role-based access control using Microsoft Entra ID groups.
- Support multi-factor authentication (MFA).
- No custom authentication or local user databases.

## Corporate Compliance
- Follow enterprise Security Development Lifecycle (SDL) practices.
- Scan all dependencies for known vulnerabilities.
- Implement audit logging per enterprise retention policies.
- Support data residency requirements for EU users.
- Accessibility: WCAG 2.1 Level AA minimum.

## Development Standards
- Back end: .NET 10 following coding conventions adopted by the organization.
- Use approved packages from internal NuGet feed.
- Minimum 80% code coverage with unit tests.
- All APIs documented with OpenAPI/Swagger.
- Structured logging using ILogger interface.

Bu ilkeleri anayasada önceden oluşturarak, çalışan portalı için oluşturulan her özelliğin kurumsal mühendislik standartlarına, güvenlik gereksinimlerine ve mimari desenlerine otomatik olarak uygun olmasını sağlarsınız. Anayasa, kurumsal bilgileri yapay zeka destekli geliştirmeye yol gösteren yürütülebilir kısıtlamalara dönüştürür.

Özet

Anayasa dosyası, GitHub Spec Kit ile belirtim temelli geliştirmede kritik bir yapıttır. Geliştirmenin her aşamasını yöneten sabit proje ilkelerini, kısıtlamalarını ve standartlarını yakalar. Bu gereksinimleri önceden tanımlayarak GitHub Copilot'un belirtim, planlama, analiz ve uygulama boyunca uyumluluğu otomatik olarak zorunlu kılabilmesini sağlarsınız.