Skip to content
Beef Docs

AI Development

AI Development Guide

Goals

  • Keep secrets and local operator state out of Git.
  • Make AI behavior reproducible across contributors.
  • Standardize MCP usage, skills, and agent instructions.

Local-Only Files (Must Stay Untracked)

  • .mcp.json
  • .claude/settings.local.json
  • apps/sirloin/.claude/settings.local.json
  • .serena/
  • apps/sirloin/.serena/
  • .playwright-mcp/

Use these tracked templates when setting up a machine:

  • .mcp.json.example
  • .claude/settings.local.example.json
  • .codex/environments/config.example.toml
  • .codex/environments/README.md

MCP Hardening Rules

  • Start from minimal server enablement (enableAllProjectMcpServers: false).
  • Enable only servers needed for the current task.
  • Never commit bearer tokens, DSNs with passwords, or API keys.
  • Prefer read-only credentials for analytics/database MCP servers.

Agent Instruction Files

  • AGENTS.md is the shared cross-agent execution contract for this repo.
  • apps/*/AGENTS.md carries Codex-scoped service notes for each app.
  • CLAUDE.md contains Claude-specific operating guidance.
  • Keep both reviewed in PRs; avoid machine-local divergence.

Project Skills

Project-local skills live in .codex/skills:

  • .codex/skills/dev-task/SKILL.md
  • .codex/skills/plan-task/SKILL.md
  • .codex/skills/plan-project/SKILL.md
  • .codex/skills/unit-testing/SKILL.md
  • .codex/skills/sirloin-billing-triage/SKILL.md
  • .codex/skills/monorepo-change-verifier/SKILL.md

These are designed to reduce repeated prompt setup for common high-cost tasks.

CI Guardrail

/scripts/check-ai-hygiene.sh runs in CI and fails when:

  • local-only AI files become tracked,
  • known secret-bearing patterns are committed.

Run locally:

Terminal window
bash scripts/check-ai-hygiene.sh