Claude Code ile Terraform Projelerini Yönetme Rehberi

Claude Code, proje klasöründe claude komutuyla başlattığınız bir kodlama ajanıdır ve Terraform projelerinde HCL dosyalarını okuyup düzenleyebilir, terminal komutları çalıştırabilir. Doğru kurulumla modül yapısını, state ve backend kurallarını öğrenir; plan-apply döngüsünü disiplinli biçimde yürütmenize yardımcı olur. Ajan, plan çıktısındaki hataları yorumlayabilir, kaynak değişikliklerinin etkisini özetleyebilir ve tekrarlayan düzenlemeleri hızlandırır. Bu rehber, Terraform bilen geliştiriciler için baştan sona pratik bir akış sunar.

Terraform işlerinde Claude Code’un güçlü yanları

Claude Code, yalnızca kod öneren statik bir araç değil; çalışma dizininizdeki dosyaları görebilen ve komut çalıştırabilen etkileşimli bir ajandır. Terraform projelerinde bu yetenek, terraform validate çıktısındaki referans hatalarını bulup düzeltmek, terraform plan çıktısını okuyup yıkıcı değişiklikleri özetlemek veya modül arayüzlerini tutarlı tutmak için doğrudan işe yarar. HCL sözdizimini, değişken ve output bağımlılıklarını anladığı için modüller arası bağlantıları korur. Ayrıca ortamlar arası benzer dosyaları (provider.tf, backend.tf, variables.tf) hızlıca üretir. Yıkıcı değişiklikleri plan çıktısından tespit edip size destroy yerine modify veya create olduğunu belirtir; ancak karar ve onay her zaman sizde kalmalıdır. Claude Code’un terminal komutlarını çalıştırabilmesi, özellikle state kilitlenmesi veya provider hatalarında size tanı koymada yardımcı olur.

Projeyi ajan için hazırlama: CLAUDE.md

Claude Code, proje kökündeki CLAUDE.md dosyasını otomatik olarak okur. Terraform projesinde bu dosya; modül klasörlerini, ortam yapısını, komutları ve state/backend kurallarını net biçimde anlatmalıdır. Aksi halde ajan genel varsayımlarla hareket eder ve örneğin terraform apply komutunu sormadan çalıştırmayı deneyebilir veya state dosyasını elle düzenlemeye kalkabilir. Aşağıdaki örnek, küçük bir Terraform reposu için başlangıç şablonudur.

# CLAUDE.md

## Dizinler
- modules/ altında tek sorumluluklu modüller; her modülde variables.tf, outputs.tf, main.tf bulunur.
- environments/dev ve environments/prod altında ortam yapılandırması.
- Her ortam kendi backend.tf dosyasında uzak state backend'ini tanımlar.

## Komutlar
- terraform fmt -check -recursive
- terraform validate
- terraform plan -out=plan.tfplan
- terraform apply plan.tfplan

## Kurallar
- terraform apply komutunu yalnızca kullanıcı onayından sonra çalıştır; önce planı göster.
- State dosyalarını elle düzenleme; terraform state komutlarını kullan.
- Kaynak değişikliklerinde önce planı göster, yıkıcı etkileri belirt.
- Provider sürümlerini versions.tf içinde sabitle.
- Her modül değişikliğinde examples/ altındaki örneği güncelle.

Bu dosyayı repo başına uyarlayın; test ve lint komutlarınız varsa ekleyin. Özellikle uzak state backend kullanıyorsanız, backend.tf içindeki yapılandırmanın değiştirilmemesi gerektiğini, yalnızca siz onay verdiğinizde değiştirilebileceğini yazın. Modül yapısı, ortam izolasyonu ve plan dosyası adlandırma gibi konularda tutarlılık sağlamak CLAUDE.md sayesinde mümkündür. Claude Code’un bu kurallara uyup uymadığını ilk oturumlarda denetleyin. Claude Code nasıl kullanılır sayfasındaki başlangıç akışı da iyi bir temel oluşturur.

Çalışma döngüsü: plan, küçük adım, test, diff

Etkili bir Terraform oturumu şu döngüyle ilerler: görevi tek bir kaynak veya modül değişikliğine indirge; Claude Code’dan değişikliği yapmasını ve plan çıktısını göstermesini iste; terraform validate ve terraform fmt -check çalıştır; git diff ile değişiklikleri gözden geçir; sonra onaylıyorsan terraform apply plan.tfplan komutunu kendin çalıştır veya ajanın çalıştırmasına izin ver. Bu döngüde her seferinde plan çıktısını incelemeden apply etmeyin; ajan size özet verse bile gerçek değişiklikleri git diff ve plan dosyasından teyit edin. Aşağıdaki promptlar tipik görevler için başlangıç noktasıdır:

• modules/networking içindeki variables.tf dosyasına cidr_block için CIDR doğrulaması ekle; sonra terraform validate çalıştır ve çıktıyı göster.
• environments/dev altında yeni bir private S3 bucket modülü ekle; önce terraform plan -out=plan.tfplan çalıştır, yıkıcı değişiklik varsa açıkça belirt.
• Aldığım hata: Error: Reference to undeclared resource. İlgili dosyayı bul, düzelt ve terraform validate ile doğrula.
• Bu modülün outputs.tf dosyasına güvenlik grubu ID’sini ekle; ardından terraform fmt -check -recursive ve terraform validate çalıştır.
• Mevcut main.tf içindeki for_each bloğunu daha okunur hale getir; ancak kaynak adreslerini değiştirme.
• versions.tf içindeki AWS provider sürümünü son kararlı 5.x sürümüne yükselt; ancak önce terraform plan ile mevcut kaynaklarda değişiklik olup olmadığını göster.
• terraform state list | grep aws_instance çıktısını incele; kullanılmayan kaynakları terraform state rm ile temizlemek için bana öneri sun, ancak komutları çalıştırma.

Her promptta küçük ve net hedef belirleyin; geniş talepler ajanın gereksiz dosyalara dokunmasına yol açar.

Claude Code’un iyi olduğu işler ve riskli noktalar

Claude Code özellikle modül taslağı çıkarma, değişken ve output ekleme, provider sürümlerini güncelleme, terraform fmt ve validate hatalarını düzeltme, ortam yapılandırmalarını kopyalama gibi işlerde hızlıdır. Ancak Terraform’da bazı alanlar geri dönüşü zor hatalara açıktır. Aşağıdaki tablo özetler:

Özellikle uzak state backend kullanıyorsanız, ajanın state kilidi veya backend yapılandırmasını değiştirmesine izin vermeden önce plan alın. terraform apply, terraform destroy, terraform state rm ve terraform import komutlarını yalnızca siz açıkça istediğinizde çalıştırmalıdır. Ajan, büyük modül refactor’larında kaynak adreslerini değiştirebilir; bu, state kaybına yol açar. Değişiklik isteğinizde ‘kaynak adresini değiştirme’ gibi açık kısıtlar verin. Ayrıca, sır yönetimi: ajan asla provider kimlik bilgileri veya terraform.tfvars içindeki gerçek değerleri öğrenmemeli; sensitive işaretli değişkenler dışa sızdırılmamalıdır.

Terraform için test ve doğrulama

Claude Code ile çalışırken doğrulamayı her adımın parçası yapın. Minimum set: terraform fmt -check -recursive (biçim), terraform validate (sözdizimi ve referanslar), terraform plan -out=plan.tfplan (gerçek değişiklikler). Bu üç komutu CLAUDE.md’ye yazın ve her değişiklik sonrası ajanın bunları çalıştırmasını zorunlu tutun. Hata çıktısı gelirse ajanın çözüm önerisini siz test edin; körlemesine düzeltmeye izin vermeyin. Modül testleriniz varsa terraform test komutunu ajanın çalıştırmasını isteyin; test yoksa kritik modüller için basit bir test iskeleti eklettirin. Örneğin, modules/s3 için tests/ altında terraform test ile bucket oluşturma ve silme senaryosunu yazmasını isteyebilirsiniz. Lint ve güvenlik taraması kullanıyorsanız (TFLint, tfsec, checkov gibi) CLAUDE.md içine komutları yazın ve her değişiklikten sonra ajanın bunları çalıştırmasını zorunlu tutun. Plan dosyasını incelemek için terraform show -json plan.tfplan | jq gibi komutlar da ajanın özet çıkarmasını kolaylaştırır. Ajan size “validate geçti” dese bile siz git diff ve plan çıktısına bakın; hatalar genellikle state uyumu, provider sürümü veya kaynak adreslemesinde saklanır. Ayrıca, plan çıktısında -/+ satırlarını ajanın açıklamasını isteyin; yanlış yorumlamaları yakalayın.

Birden fazla ajanı AgentVera ile paralel çalıştırma

Terraform projesinde birden fazla Claude Code ajanını paralel çalıştırmak için AgentVera kullanabilirsiniz. Her ajan kendi git worktree’sinde çalıştığı için aynı dosyaları ezme riski ortadan kalkar; otomatik kod incelemesi plan ve state değişikliklerini ikinci bir modelin gözünden geçirir. Checkpoints sayesinde hatalı bir adımı tek tıkla geri alabilir, token bütçeleriyle ajanların kaynak kullanımını sınırlayabilirsiniz. Bu, özellikle modül geliştirme ve ortam güncelleme işlerini paralelleştirirken güvenli bir çalışma zemini oluşturur. Daha fazlası için Birden fazla Claude Code ajanını paralel çalıştırma ve AgentVera nasıl kullanılır sayfalarına bakabilirsiniz.

Özet

Claude Code, Terraform projelerinde iyi bir yardımcıdır; yeter ki CLAUDE.md ile repo kurallarını ve komutları net biçimde tanımlayın. Plan-apply döngüsünde küçük adımlar atın, doğrulama komutlarını her değişiklikten sonra çalıştırın ve state/backend/apply gibi kritik noktalarda onayı elden bırakmayın. Paralel çalışma gerekirse git worktree tabanlı bir kurulumla ajanları izole edin; böylece hız kazanırken altyapı güvenliğini korursunuz. Unutmayın: ajan iyi bir yardımcıdır ama son karar sizin.