Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (93 loc) · 5.43 KB

AGENTS.md

File metadata and controls

124 lines (93 loc) · 5.43 KB

AGENTS.md

Precedence: the closest AGENTS.md to the files you're changing wins. Root holds global defaults only.

Project Overview

Devcontainer bundling four AI coding agents (Claude Code, Copilot CLI, OpenCode, Codex) with Pulumi, K8s tooling, and skills/agents/hooks/MCP servers via yaah. Also includes a Docker AI Sandbox image for lightweight Claude Code environments. Configuration-only project — no app source, no builds, no tests.

Commands

Task Command
Regenerate all agent configs yaah generate
Generate for one agent yaah generate -a claude
Lint (inside container) yaah lint
Secret scan yaah scan_secrets
Validate devcontainer Rebuild container in VS Code
Build Docker sandbox docker build -t dirien/sandbox-claude-iac:latest docker-sandbox/

No typecheck, test, or build commands — this is devcontainer config.

Workflow

  1. Before coding: Read this file
  2. After devcontainer.json changes: Verify valid JSON
  3. After skill/agent/hook changes: yaah generate
  4. Before committing: No secrets in any files

File Map

.devcontainer/devcontainer.json  # Devcontainer definition (image, features, env, ports)
.devcontainer/banner.sh          # Startup banner (tool versions + auth)
docker-sandbox/Dockerfile        # Docker AI Sandbox image (claude-code-minimal + pulumi, helm, kubectl)
.gitignore                       # Ignores yaah-generated dirs (.claude/, .codex/, .copilot/, .opencode/, .agents/, .github/agents|hooks|skills/)
docs/tools-and-skills.md         # Canonical reference: all agents, skills, hooks, MCP servers

Generated by yaah (do not edit, gitignored):

.claude/settings.json            # Claude Code settings (model, hooks, MCP, LSP)
.claude/agents/                  # Sub-agents
.claude/skills/                  # Skills
.mcp.json                        # MCP server config (context7, pulumi, yaah)
.codex/                          # Codex agent config
.copilot/                        # Copilot agent config
.opencode/                       # OpenCode agent config
opencode.json                    # OpenCode config
.agents/                         # Shared agent config
.github/agents/                  # GitHub agents config
.github/hooks/                   # GitHub hooks config
.github/skills/                  # GitHub skills config

Key Configuration

Features (devcontainer):

  • node, python, go, github-cli (devcontainers official)
  • claude-code (anthropics)
  • copilot-cli (devcontainers)
  • opencode v1.3.13 (ghcr.io/dirien/devcontainer-features/opencode)
  • kubectl + helm (devcontainers, no minikube)
  • yaah v0.3.3 (ghcr.io/dirien/devcontainer-feature-yaah/yaah)
  • codex (ghcr.io/dirien/devcontainer-feature-codex/codex)
  • pulumi (ghcr.io/dirien/devcontainer-feature-pulumi/pulumi)

Env vars (forwarded from host): ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN, PULUMI_ACCESS_TOKEN

MCP servers: context7 (stdio, docs), pulumi (HTTP, IaC), yaah (stdio, scan/lint/guard)

Hooks: Linter (PostToolUse), CommandGuard (PreToolUse/Bash), SecretScanner (PostToolUse), CommentChecker (PostToolUse), SessionLogger (session lifecycle)

Ports: 19999 (Claude OAuth), 4096 (OpenCode API), 4097 (OpenCode Web), 3000/8000/8080 (dev servers)

Docker Sandbox: docker-sandbox/Dockerfile extends docker/sandbox-templates:claude-code-minimal with kubectl, helm, pulumi. Test with sbx run --template docker.io/dirien/sandbox-claude-iac:latest claude.

Heuristics

When Do
Adding a tool Devcontainer feature or postCreateCommand in devcontainer.json
Modifying agent/skill/hook Edit yaah source → yaah generate
Adding MCP server Add to both .mcp.json and .claude/settings.json
Adding a port forwardPorts + portsAttributes in devcontainer.json
Adding a devcontainer feature Create standalone repo dirien/devcontainer-feature-<name> with CI workflows

Boundaries

Always Do

  • Keep devcontainer.json valid JSON
  • Use conventional commits: type(scope): subject
  • Keep .claude/settings.json in sync with .mcp.json for MCP servers

Ask First

  • Adding devcontainer features, changing versions, modifying hooks, changing base image

Never Do

  • Commit secrets/tokens
  • Edit yaah-generated files directly (.claude/agents/, .claude/skills/, .codex/, .copilot/, .opencode/, .agents/, .github/agents|hooks|skills/)
  • Remove claude-config volume mount
  • Push directly to main

Terminology

Term Means
yaah Yet Another Agent Harness — generates configs for all four agents
devcontainer feature OCI component installed via devcontainer spec
MCP server Model Context Protocol server providing tools to AI agents
skill Domain-specific prompt/knowledge module for coding agents
hook Shell command triggered by agent lifecycle events
Docker sandbox Lightweight VM via sbx run for AI coding agents (Docker AI Sandboxes)

Index of scoped AGENTS.md

None — flat configuration project with no subdirectory-specific conventions.

When instructions conflict

The nearest AGENTS.md wins. Explicit user prompts override files.