Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

KCL Guidelines Implementation Summary

Date: 2025-10-03 Status: ✅ Complete Purpose: Consolidate KCL rules and patterns for the provisioning project

📋 What Was Created

1. Comprehensive KCL Patterns Guide

File: .claude/kcl_idiomatic_patterns.md (1,082 lines)

Contents:

  • 10 Fundamental Rules - Core principles for KCL development
  • 19 Design Patterns - Organized by category:
    • Module Organization (3 patterns)
    • Schema Design (5 patterns)
    • Validation (3 patterns)
    • Testing (2 patterns)
    • Performance (2 patterns)
    • Documentation (2 patterns)
    • Security (2 patterns)
  • 6 Anti-Patterns - Common mistakes to avoid
  • Quick Reference - DOs and DON’Ts
  • Project Conventions - Naming, aliases, structure
  • Security Patterns - Secure defaults, secret handling
  • Testing Patterns - Example-driven, validation test cases

2. Quick Rules Summary

File: .claude/KCL_RULES_SUMMARY.md (321 lines)

Contents:

  • 10 Fundamental Rules (condensed)
  • 19 Pattern quick reference
  • Standard import aliases table
  • 6 Critical anti-patterns
  • Submodule reference map
  • Naming conventions
  • Security/Validation/Documentation checklists
  • Quick start template

3. CLAUDE.md Integration

File: CLAUDE.md (updated)

Added:

  • KCL Development Guidelines section
  • Reference to .claude/kcl_idiomatic_patterns.md
  • Core KCL principles summary
  • Quick KCL reference code example

🎯 Core Principles Established

1. Direct Submodule Imports

✅ import provisioning.lib as lib
❌ Settings = settings.Settings  # ImmutableError

2. Schema-First Development

Every configuration must have a schema with validation.

3. Immutability First

Use KCL’s immutable-by-default, only use _ prefix when absolutely necessary.

4. Security by Default

  • Secrets as references (never plaintext)
  • TLS enabled by default
  • Certificates verified by default

5. Explicit Types

  • Always specify types
  • Use union types for enums
  • Mark optional with ?

📚 Rule Categories

Module Organization (3 patterns)

  1. Submodule Structure - Domain-driven organization
  2. Extension Organization - Consistent hierarchy
  3. kcl.mod Dependencies - Relative paths + versions

Schema Design (5 patterns)

  1. Base + Provider - Generic core, specific providers
  2. Configuration + Defaults - System defaults + user overrides
  3. Dependency Declaration - Explicit with version ranges
  4. Version Management - Metadata & update strategies
  5. Workflow Definition - Declarative operations

Validation (3 patterns)

  1. Multi-Field Validation - Cross-field rules
  2. Regex Validation - Format validation with errors
  3. Resource Constraints - Validate limits

Testing (2 patterns)

  1. Example-Driven Schemas - Examples in documentation
  2. Validation Test Cases - Test cases in comments

Performance (2 patterns)

  1. Lazy Evaluation - Compute only when needed
  2. Constant Extraction - Module-level reusables

Documentation (2 patterns)

  1. Schema Documentation - Purpose, fields, examples
  2. Inline Comments - Explain complex logic

Security (2 patterns)

  1. Secure Defaults - Most secure by default
  2. Secret References - Never embed secrets

🔧 Standard Conventions

Import Aliases

ModuleAlias
provisioning.liblib
provisioning.settingscfg or settings
provisioning.dependenciesdeps or schema
provisioning.workflowswf
provisioning.batchbatch
provisioning.versionv
provisioning.k8s_deployk8s

Schema Naming

  • Base: Storage, Server, Cluster
  • Provider: Storage_aws, ServerDefaults_upcloud
  • Taskserv: Kubernetes, Containerd
  • Config: NetworkConfig, MonitoringConfig

File Naming

  • Main schema: {name}.k
  • Defaults: defaults_{provider}.k
  • Server: server_{provider}.k
  • Dependencies: dependencies.k
  • Version: version.k

⚠️ Critical Anti-Patterns

1. Re-exports (ImmutableError)

❌ Settings = settings.Settings

2. Mutable Non-Prefixed Variables

❌ config = { host = "local" }
   config = { host = "prod" }  # Error!

3. Missing Validation

❌ schema ServerConfig:
    cores: int  # No check block!

4. Magic Numbers

❌ timeout: int = 300  # What's 300?

5. String-Based Configuration

❌ environment: str  # Use union types!

6. Deep Nesting

❌ server: { network: { interfaces: { ... } } }

📊 Project Integration

Files Updated/Created

Created (3 files):

  1. .claude/kcl_idiomatic_patterns.md - 1,082 lines

    • Comprehensive patterns guide
    • All 19 patterns with examples
    • Security and testing sections

  2. .claude/KCL_RULES_SUMMARY.md - 321 lines

    • Quick reference card
    • Condensed rules and patterns
    • Checklists and templates

  3. KCL_GUIDELINES_IMPLEMENTATION.md - This file

    • Implementation summary
    • Integration documentation

Updated (1 file):

  1. CLAUDE.md
    • Added KCL Development Guidelines section
    • Reference to comprehensive guide
    • Core principles summary

🚀 How to Use

For Claude Code AI

CLAUDE.md now includes:

## KCL Development Guidelines

For KCL configuration language development, reference:
- @.claude/kcl_idiomatic_patterns.md (comprehensive KCL patterns and rules)

### Core KCL Principles:
1. Direct Submodule Imports
2. Schema-First Development
3. Immutability First
4. Security by Default
5. Explicit Types

For Developers

Quick Start:

  1. Read .claude/KCL_RULES_SUMMARY.md (5-10 minutes)
  2. Reference .claude/kcl_idiomatic_patterns.md for details
  3. Use quick start template from summary

When Writing KCL:

  1. Check import aliases (use standard ones)
  2. Follow schema naming conventions
  3. Use quick start template
  4. Run through validation checklist

When Reviewing KCL:

  1. Check for anti-patterns
  2. Verify security checklist
  3. Ensure documentation complete
  4. Validate against patterns

📈 Benefits

Immediate

  • ✅ All KCL patterns documented in one place
  • ✅ Clear anti-patterns to avoid
  • ✅ Standard conventions established
  • ✅ Quick reference available

Long-term

  • ✅ Consistent KCL code across project
  • ✅ Easier onboarding for new developers
  • ✅ Better AI assistance (Claude follows patterns)
  • ✅ Maintainable, secure configurations

Quality Improvements

  • ✅ Type safety (explicit types everywhere)
  • ✅ Security by default (no plaintext secrets)
  • ✅ Validation complete (check blocks required)
  • ✅ Documentation complete (examples required)

🔗 Related Documentation

KCL Guidelines (New)

  • .claude/kcl_idiomatic_patterns.md - Full patterns guide
  • .claude/KCL_RULES_SUMMARY.md - Quick reference
  • CLAUDE.md - Project rules (updated with KCL section)

KCL Architecture

  • docs/architecture/kcl-import-patterns.md - Import patterns deep dive
  • docs/KCL_QUICK_REFERENCE.md - Developer quick reference
  • KCL_MODULE_ORGANIZATION_SUMMARY.md - Module organization

Core Implementation

  • provisioning/kcl/main.k - Core module (cleaned up)
  • provisioning/kcl/*.k - Submodules (10 files)
  • provisioning/extensions/ - Extensions (providers, taskservs, clusters)

✅ Validation

Files Verified

# All guides created
ls -lh .claude/*.md
# -rw-r--r--  16K  best_nushell_code.md
# -rw-r--r--  24K  kcl_idiomatic_patterns.md  ✅ NEW
# -rw-r--r--  7.4K KCL_RULES_SUMMARY.md      ✅ NEW

# Line counts
wc -l .claude/kcl_idiomatic_patterns.md  # 1,082 lines ✅
wc -l .claude/KCL_RULES_SUMMARY.md       #   321 lines ✅

# CLAUDE.md references
grep "kcl_idiomatic_patterns" CLAUDE.md
# Line 8:  - **Follow KCL idiomatic patterns from @.claude/kcl_idiomatic_patterns.md**
# Line 18: - @.claude/kcl_idiomatic_patterns.md (comprehensive KCL patterns and rules)
# Line 41: See full guide: `.claude/kcl_idiomatic_patterns.md`

Integration Confirmed

  • ✅ CLAUDE.md references new KCL guide (3 mentions)
  • ✅ Core principles summarized in CLAUDE.md
  • ✅ Quick reference code example included
  • ✅ Follows same structure as Nushell guide

🎓 Training Claude Code

What Claude Will Follow

When Claude Code reads CLAUDE.md, it will now:

  1. Import Correctly

    • Use import provisioning.{submodule}
    • Never use re-exports
    • Use standard aliases

  2. Write Schemas

    • Define schema before config
    • Include check blocks
    • Use explicit types

  3. Validate Properly

    • Cross-field validation
    • Regex for formats
    • Resource constraints

  4. Document Thoroughly

    • Schema docstrings
    • Usage examples
    • Test cases in comments

  5. Secure by Default

    • TLS enabled
    • Secret references only
    • Verify certificates

📋 Checklists

For New KCL Files

Schema Definition:

  • Explicit types for all fields
  • Check block with validation
  • Docstring with purpose
  • Usage examples included
  • Optional fields marked with ?
  • Sensible defaults provided

Imports:

  • Direct submodule imports
  • Standard aliases used
  • No re-exports
  • kcl.mod dependencies declared

Security:

  • No plaintext secrets
  • Secure defaults
  • TLS enabled
  • Certificates verified

Documentation:

  • Header comment with info
  • Schema docstring
  • Complex logic explained
  • Examples provided

🔄 Next Steps (Optional)

Enhancement Opportunities

  1. IDE Integration

    • VS Code snippets for patterns
    • KCL LSP configuration
    • Auto-completion for aliases

  2. CI/CD Validation

    • Check for anti-patterns
    • Enforce naming conventions
    • Validate security settings

  3. Training Materials

    • Workshop slides
    • Video tutorials
    • Interactive examples

  4. Tooling

    • KCL linter with project rules
    • Schema generator using templates
    • Documentation generator

📊 Statistics

Documentation Created

  • Total Files: 3 new, 1 updated
  • Total Lines: 1,403 lines (KCL guides only)
  • Patterns Documented: 19
  • Rules Documented: 10
  • Anti-Patterns: 6
  • Checklists: 3 (Security, Validation, Documentation)

Coverage

  • ✅ Module organization
  • ✅ Schema design
  • ✅ Validation patterns
  • ✅ Testing patterns
  • ✅ Performance patterns
  • ✅ Documentation patterns
  • ✅ Security patterns
  • ✅ Import patterns
  • ✅ Naming conventions
  • ✅ Quick templates

🎯 Success Criteria

All criteria met:

  • ✅ Comprehensive patterns guide created
  • ✅ Quick reference summary available
  • ✅ CLAUDE.md updated with KCL section
  • ✅ All rules consolidated in .claude folder
  • ✅ Follows same structure as Nushell guide
  • ✅ Examples and anti-patterns included
  • ✅ Security and testing patterns covered
  • ✅ Project conventions documented
  • ✅ Integration verified

📝 Conclusion

Successfully created comprehensive KCL guidelines for the provisioning project:

  1. .claude/kcl_idiomatic_patterns.md - Complete patterns guide (1,082 lines)
  2. .claude/KCL_RULES_SUMMARY.md - Quick reference (321 lines)
  3. CLAUDE.md - Updated with KCL section

All KCL development rules are now:

  • ✅ Documented in .claude folder
  • ✅ Referenced in CLAUDE.md
  • ✅ Available to Claude Code AI
  • ✅ Accessible to developers

The project now has a single source of truth for KCL development patterns.

Maintained By: Architecture Team Review Cycle: Quarterly or when KCL version updates Last Review: 2025-10-03