sidekick: Instructions file for Codex

AGENTS.md - Tool Creation & Style Guide

This guide explains how to create tools for the Pydantic AI-based personal AI agent and follow consistent code style.

For Claude Code users: See CLAUDE.md for quick reference and MCP documentation.

Response Guidelines

• 답변 언어: 항상 한국어로 응답
• 답변 스타일: 핵심만 요약해서 간결하게
• Git 컨벤션: docs/GIT_CONVENTIONS.md 참조

Tool Architecture

Tools are plain Python functions registered with Pydantic AI's FunctionToolset.

src/
├── config.py             # pydantic-settings 기반 Settings 클래스
├── interfaces/           # Entry points
│   ├── slack/           # Slack bot integration (모듈화됨)
│   │   ├── bot.py       # 이벤트 라우터 (127줄)
│   │   ├── handlers.py  # 이벤트 핸들러
│   │   ├── context.py   # 스레드/채널 컨텍스트
│   │   ├── images.py    # 이미지 처리
│   │   ├── progress.py  # 진행 상태 포맷팅
│   │   └── slack_api.py # Slack API 유틸리티
│   └── api/             # FastAPI REST API
│       ├── main.py      # FastAPI app
│       ├── security.py  # API 키 인증 + Rate Limiting
│       ├── schemas.py   # Pydantic 요청/응답 모델
│       ├── tasks.py     # 백그라운드 작업 + 웹훅
│       └── task_repository.py # SQLite 작업 영속성
├── middleware/          # Cross-cutting concerns
│   ├── guardrails/      # Security guardrails
│   │   ├── core.py      # Generic guardrail framework (서버 규칙 집계)
│   │   └── enforcer.py  # 모든 도구 유형 보호 (Defense in Depth)
│   ├── preprocessing/   # 요청 전처리
│   │   └── __init__.py  # preprocess_command(), core 모듈 re-export
│   └── postprocessing/  # 응답 후처리 (최소화)
├── core/                # Core business logic
│   ├── agent/           # AgentRunner, AgentFactory
│   │   ├── core.py      # Backward-compat re-exports
│   │   ├── utils.py     # AgentRunResult, retry, image normalization
│   │   ├── factory.py   # AgentFactory (isolated agent 생성)
│   │   └── runner.py    # AgentRunner (run/run_async + 이미지 추출)
│   ├── context/         # 요청 컨텍스트 관리 (ContextVar)
│   │   └── image.py     # 첨부 이미지 컨텍스트 + bounded LRU 캐시
│   ├── scheduler/       # Task scheduling system
│   ├── commands/        # Command system
│   ├── lifecycle.py     # 싱글톤 라이프사이클 관리
│   └── memory/          # Memory/graph system
├── tools/               # Tool definitions
│   ├── catalog.py       # 통합 ToolCatalog
│   ├── mcp_registry.py  # MCPServerConfig, ServerGuardrailRules, register_mcp_server()
│   ├── mcp_client.py    # MCPManager (다중 MCP 서버 연결)
│   ├── mcp/             # MCP server definitions (register_mcp_server, gitignored)
│   ├── custom/          # Custom tools (@register_tool, gitignored)
│   └── registry.py      # Tool registration
└── utils/               # Utilities
    ├── logging.py       # 구조화 로깅 (JSON + request_id)
    ├── observability.py # Logfire 통합
    ├── image_handler.py # ImageData, extract_images_from_result()
    ├── slack_files.py   # Slack 파일 다운로드/업로드 유틸리티
    └── slack_formatter.py # Markdown → Slack mrkdwn 변환