anchor-stack CLAUDE.md

CLAUDE.md - Anchor Stack Project Instructions

This file contains instructions for Claude Code when working on this project.

Project Overview

• Project Name: Anchor Stack
• Type: MCP Server (Model Context Protocol)
• Language: Python 3.10+
• Purpose: AI-friendly engineering foundation with stable versions, unified logging, and pluggable capability packs

Directory Structure

Modifiable Directories

• src/anchor_stack/tools/ - MCP tool implementations
• src/anchor_stack/services/ - Core business logic
• src/anchor_stack/models/ - Pydantic data models
• stacks/ - Stack template definitions
• packs/ - Pack template definitions
• tests/ - Test files

Protected Directories (Do Not Modify Without Understanding)

• src/anchor_stack/core/ - Framework essentials (logger, config, exceptions)

Code Standards

Logging

Always use the built-in logger, NOT print():

from anchor_stack.core.logger import get_logger

logger = get_logger(__name__)

# Correct usage
logger.info("Operation completed", extra={"task_id": 123, "status": "success"})
logger.error("Operation failed", extra={"error": str(e), "context": ctx})
logger.debug("Debug info", extra={"data": data})

# INCORRECT - Never use
print("Operation completed")  # ❌

Configuration

All configuration should use pydantic-settings:

from anchor_stack.core.config import get_settings

settings = get_settings()
# Access settings.log_level, settings.stacks_dir, etc.

# INCORRECT - Never hardcode
LOG_LEVEL = "DEBUG"  # ❌

Exceptions

Use custom exceptions from core.exceptions:

from anchor_stack.core.exceptions import (
    StackNotFoundError,
    PackNotFoundError,
    TemplateRenderError,
)

# Raise with context
raise StackNotFoundError(
    "Stack not found",
    stack_type="nextjs",
    version="2025.1"
)

Type Hints

All functions must have type hints:

# Correct
def process_data(items: list[str], count: int = 10) -> dict[str, Any]:
    ...

# INCORRECT
def process_data(items, count=10):  # ❌
    ...