Terraform Cloud Mcp CLAUDE.md

> Sourced from [severity1/terraform-cloud-mcp](https://github.com/severity1/terraform-cloud-mcp) — [MIT](https://github.com/severity1/terraform-cloud-mcp/blob/2e7865580438c97cd5ce115e357b6ac320b2c323/CLAUDE.md).

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Terraform Cloud MCP Development Guide

## Subtree Discovery System

This project uses Claude Code's automatic subtree discovery for context-aware guidance. Component-specific CLAUDE.md files are automatically loaded when working in their directories:

- **docs/** - Documentation standards and templates
- **terraform_cloud_mcp/tools/** - MCP tools implementation patterns  
- **terraform_cloud_mcp/models/** - Pydantic models and validation
- **terraform_cloud_mcp/utils/** - Utility functions and error handling
- **terraform_cloud_mcp/api/** - API client patterns

## Working Directory Guidance

### When Working on Tool Implementation
- **Directory**: `terraform_cloud_mcp/tools/`
- **Context**: Automatic loading of tools-specific patterns
- **Focus**: MCP function signatures, error handling, API integration

### When Working on Data Models
- **Directory**: `terraform_cloud_mcp/models/`
- **Context**: Automatic loading of model validation patterns
- **Focus**: Pydantic models, validation rules, type definitions

### When Working on Utilities
- **Directory**: `terraform_cloud_mcp/utils/`
- **Context**: Automatic loading of utility function patterns
- **Focus**: Error handling, API helpers, common operations

### When Working on API Client
- **Directory**: `terraform_cloud_mcp/api/`
- **Context**: Automatic loading of API client patterns
- **Focus**: HTTP client, authentication, request handling

### When Working on Documentation
- **Directory**: `docs/`
- **Context**: Automatic loading of documentation standards
- **Focus**: Templates, formatting, structure requirements

## Development Commands

### Quality Checks
- **Format**: `ruff format .`
- **Lint**: `ruff check .`
- **Type Check**: `mypy .`
- **Test**: `pytest`

### Build Commands
- **Install**: `uv pip install -e .`
- **Dev Install**: `uv pip install -e .[dev]`
- **Requirements**: `uv pip compile requirements.in`

## Core Principles

### Decision-Making Process
1. **Use component guidance**: Let subtree discovery load relevant context
2. **Apply documented patterns**: Follow loaded component standards
3. **Avoid code inference**: Use documented criteria only
4. **Validate against patterns**: Check implementation against guidance

### Task Complexity Assessment
- **Simple** (< 2 hours): Direct implementation, minimal planning
- **Medium** (2-8 hours): Use TodoWrite for 3-5 tasks
- **Complex** (> 8 hours): Use subagents (2-6) with comprehensive TodoWrite planning

## Documentation Standards

### Required Documentation Updates
For any new implementation, always update:
- **TASKS.md**: Move features from planned to completed status
- **docs/API_REFERENCES.md**: Mark corresponding API sections as implemented  
- **docs/DEVELOPMENT.md**: Add new patterns if applicable
- **docs/CONTRIBUTING.md**: Update contribution guidelines if new patterns introduced

### Implementation Standards  
- **Use utility functions**: `create_api_payload()`, `query_params()`, `@handle_api_errors`
- **Apply response filtering**: Automatic filtering system in `utils/filters.py` handles all GET requests
- **Follow component patterns**: Apply standards from automatically loaded component CLAUDE.md files
- **Run quality checks**: Format, lint, type check before completion
- **Update relevant documentation**: Maintain consistency across project

### Response Filtering Implementation Context
This MCP server implements audit-safe response filtering with the following constraints:
- **Primary use case**: Audit and compliance scenarios requiring complete data integrity
- **Filtering approach**: Conservative token optimization (5-15% reduction) to preserve audit trails
- **Critical preservation requirements**: 
  - User accountability data (`created-at`, `updated-at`, `version-id`)
  - Security configuration (permissions, auth policies)
  - Change tracking (status timestamps, source information)
  - Operational context (status, timing, progress indicators)
- **Decision principle**: Preserve fields when audit impact is uncertain
- **Implementation location**: `utils/filters.py` with configurations in `configs/filter_configs.py`

## Task Management

### TodoWrite Usage
Use TodoWrite for tasks with:
- Multiple distinct steps (> 2)
- Multiple file changes
- Cross-component coordination
- Medium to complex scope

### Progress Standards  
- Mark todos `in_progress` before starting
- Mark `completed` immediately after finishing
- Update status in real-time
- Provide concise progress updates for major phases

## Memory System Maintenance

### Periodic Review Schedule
- **Monthly**: Review component CLAUDE.md files for outdated patterns
- **After major features**: Update decision matrices and workflow patterns
- **When adding new domains**: Verify subtree discovery optimization
- **Quality check failures**: Review and update development standards

### Maintenance Triggers
- **New implementation patterns**: Update relevant component guidance
- **API changes**: Review model and tool implementation standards  
- **Development workflow changes**: Update quality check commands
- **Documentation structure changes**: Update docs/ guidance
- **Filter configuration changes**: When new API fields appear, assess preservation vs. optimization trade-offs
- **Compliance requirement changes**: Review filter configurations if audit use cases evolve

### Memory Optimization Indicators
- **High context usage**: Review for redundant information across files
- **Frequent cross-referencing**: Consider consolidating related guidance
- **Outdated patterns**: Remove deprecated implementation approaches
- **Missing decision criteria**: Add decision matrices for common scenarios