Improve codebase organization for AI-assisted development#141
Draft
ian-flores wants to merge 8 commits intomainfrom
Draft
Improve codebase organization for AI-assisted development#141ian-flores wants to merge 8 commits intomainfrom
ian-flores wants to merge 8 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.
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
1 participant
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/