Sókrates Wiki

CLAUDE.md Standards and AI Agent Configuration

3 min read

CLAUDE.md Standards and AI Agent Configuration

Summary

This page defines the architectural constraints, coding standards, and operational rules for AI agents (specifically Claude) interacting with the Sokrates project. It establishes the requirements for CLAUDE.md files across the monorepo, the global configuration in ~/.claude/CLAUDE.md, and the integration of custom Claude Code skills.

Details

Global AI Standards

The global configuration file (~/.claude/CLAUDE.md) serves as the primary source of truth for developer preferences across all projects. Key invariants include:

  • Type Checking: The project has migrated from pyright to ty. All new code must be validated using ty.
  • Python Web/HTTP Stack:
    • Framework: FastAPI is the default for web services.
    • Server: uvicorn is the standard ASGI server.
    • HTTP Client: httpx must be used for all HTTP requests; the requests library is explicitly banned.
    • Configuration: pydantic-settings is used for environment variable management.
    • CLI: Typer is the standard for command-line interfaces.
  • Observability: structlog is the mandatory logging implementation. Logfire is utilized as the OpenTelemetry (OTEL) backend, plugging into the system as a structlog processor.
  • Integration: The Model Context Protocol (MCP) is the standard integration pattern for all agentic tools and services.

Sokrates Monorepo Documentation Structure

The Sokrates project uses a tiered CLAUDE.md structure to provide context-aware guidance to AI agents:

  1. Root (./CLAUDE.md): Documents the uv workspace layout, the just task runner commands, and the Nix flake targets (sokrates-dev, sokrates-box, sokrates-ctl). It also outlines the security boundary enforced by nftables and the ongoing migration from the “eidos” naming convention (formerly “grimoire”).
  2. Eidos (./eidos/CLAUDE.md): Focuses on the Hyle type system, specifically error handling patterns and query architecture. It mandates the use of discriminated unions for domain models and defines the startup sequence for the FastAPI/Neo4j stack.
  3. Hermes Agent (./hermes-agent/CLAUDE.md): Notes the component’s status and its role as the primary agentic gateway.
  4. Plugin/CLI (./plugin/cli/CLAUDE.md): Provides specific build instructions and environment variable configurations for the sokrates-ctl tool.

Audit and Quality Metrics

A comprehensive audit of the Sokrates ecosystem identified varying levels of documentation maturity. Projects are graded on criteria such as command actionability, architecture clarity, and currency of tooling.

  • High Quality (A/B): residual-modeling, connectwise-etl, Autopod, and sokrates-website maintain high standards with clear modeling pipelines and design system tokens.
  • Legacy/Inactive: SETS, memory-palace, eidos (legacy), and debate_club are currently inactive. While they contain stale references to pyright and redundant error-handling code, they are not prioritized for updates.
  • Third-Party: The mcp-sdk contains upstream Anthropic conventions (e.g., pre-commit, line length 88) which intentionally conflict with the Sokrates global standards.

Claude Code Skills and Plugins

The project utilizes local plugins to extend Claude Code’s capabilities.

  • Zed Configuration: A specific skill for managing Zed editor settings and keybindings is installed at ~/.claude/plugins/local/zed-config/.
  • Plugin Manifests: For a local plugin to be discovered by Claude Code, it must contain a .claude-plugin/plugin.json manifest file. Discovery is triggered via the /reload-plugins command.

Graph View

Backlinks