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

Use component guidance: Let subtree discovery load relevant context
Apply documented patterns: Follow loaded component standards
Avoid code inference: Use documented criteria only
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

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

Use component guidance: Let subtree discovery load relevant context
Apply documented patterns: Follow loaded component standards
Avoid code inference: Use documented criteria only
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

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password