Improve codebase organization for AI-assisted development#141
Open
ian-flores wants to merge 10 commits intomainfrom
Open
Improve codebase organization for AI-assisted development#141ian-flores wants to merge 10 commits intomainfrom
ian-flores wants to merge 10 commits intomainfrom
Conversation
…assisted development Add three architecture docs covering config flow (YAML→Go→Python), step dependencies and execution pipeline, and Pulumi conventions (resource naming, autoload pattern, Output[T] handling). Enhance CLAUDE.md with danger zones, key patterns, and Python Pulumi development guidance to prevent common mistakes like accidental resource destruction from name changes.
Add targeted docstrings to the 5 largest Python files documenting constructor patterns (builder vs all-in-init vs autoload), method ordering dependencies, critical Pulumi state names, and Go/Python config sync requirements. No logic changes — documentation only.
Add a validation script (scripts/validate-config-sync.py) that compares Go struct YAML tags against Python dataclass fields to catch config drift between the two languages. Integrate into CI and Justfile. Standardize Python Pulumi test infrastructure with shared fixtures in conftest.py (ptd_root, pulumi_mocks, aws_workload, azure_workload) and comprehensive TESTING.md guide covering both test paradigms.
…docstrings Add Azure naming conventions (CAF prefixes, character limits), AKS step details (Go-based unlike Python EKS), and Azure-specific gotchas to all three architecture docs and CLAUDE.md. Add inline docstrings to the 3 largest Azure Pulumi files documenting constructor patterns and resource naming constraints.
Fix sentence case in ~80 headings, expand ~12 acronyms on first use (IAM, EKS, AKS, VPC, RDS, etc.), remove ~15 instances of bold-for-emphasis, fix ~6 passive voice instances, use long-form product names on first mention, and add custom IDs to all Step headings.
Remove unused imports (pytest, typing), suppress ARG001/ARG002 for pytest fixture args and Pulumi interface method args that are required by the interface but unused in the implementation, and fix import ordering.
…oad fixture These fields were removed from AzureWorkloadConfig in the refactor commit 98a1120. Updated the test fixture to match the current schema.
Lytol
reviewed
Mar 9, 2026
Contributor
Lytol
left a comment
Lytol
left a comment
There was a problem hiding this comment.
I can't say that I read every line, but everything I did read seems like a nice improvement to the docs (for both agents and humans). Thanks so much!
Comment on lines
+679
to
+740
| ### 5. Azure storage account names with hyphens (Azure-specific) | ||
| **Mistake:** | ||
| ```python | ||
| # ❌ WRONG - Azure storage accounts cannot have hyphens | ||
| storage_account_name = f"stptd-{compound_name}" | ||
| ``` | ||
|
|
||
| **Impact:** Azure API rejects the resource creation with a validation error. | ||
|
|
||
| **Fix:** | ||
| ```python | ||
| # ✅ Correct - remove ALL hyphens | ||
| name = compound_name.replace("-", "") | ||
| storage_account_name = f"stptd{name[:19]}" | ||
| ``` | ||
|
|
||
| **Why this happens:** AI models trained on AWS patterns often add hyphens, but Azure storage accounts only allow lowercase alphanumeric characters (no hyphens, no underscores). | ||
|
|
||
| --- | ||
|
|
||
| ### 6. Azure resource names exceeding character limits (Azure-specific) | ||
| **Mistake:** | ||
| ```python | ||
| # ❌ WRONG - Key Vault names can't exceed 24 chars | ||
| key_vault_name = f"kv-ptd-{very_long_compound_name}" # Could be 30+ chars | ||
| ``` | ||
|
|
||
| **Impact:** Azure API rejects the resource with a length validation error. | ||
|
|
||
| **Fix:** | ||
| ```python | ||
| # ✅ Correct - truncate to fit within limits | ||
| name = compound_name[:17] # Leave room for "kv-ptd-" prefix | ||
| key_vault_name = f"kv-ptd-{name}" | ||
| ``` | ||
|
|
||
| **Azure character limits:** | ||
| - Key Vault: 24 chars max | ||
| - Storage Account: 24 chars max | ||
| - Most other resources: 64-80 chars (more lenient) | ||
|
|
||
| --- | ||
|
|
||
| ### 7. Incorrect Azure tag key format (Azure-specific) | ||
| **Mistake:** | ||
| ```python | ||
| # ❌ WRONG - Azure doesn't allow dots in tag keys | ||
| tags = {"posit.team/environment": "staging"} | ||
| ``` | ||
|
|
||
| **Impact:** Azure silently converts or rejects the tags, leading to inconsistent tagging. | ||
|
|
||
| **Fix:** | ||
| ```python | ||
| # ✅ Correct - use azure_tag_key_format() helper | ||
| tags = { | ||
| ptd.azure_tag_key_format("posit.team/environment"): "staging" | ||
| } | ||
| # Converts dots to forward slashes: "posit/team/environment" | ||
| ``` | ||
|
|
||
| --- |
Contributor
There was a problem hiding this comment.
Should we just generically reference https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules rather than just the specific rules that we've encountered?
Lytol
approved these changes
Mar 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Motivation
AI assistants (and new contributors) struggle with two things in this codebase:
These changes codify tribal knowledge into documentation and add guardrails to prevent common mistakes.
Test plan
python3 scripts/validate-config-sync.py)lib/types/orpython-pulumi/