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 cross-harness service notes for each app.
  • CLAUDE.md imports the nearest AGENTS.md; do not duplicate guidance there.

Project Skills

Portable project skills live in .agents/skills; .claude/skills contains compatibility symlinks to the same files. The set covers task planning and delivery, change verification, docs, shared contracts, Brain migrations, billing triage, unit testing, Foxy design/process work, and Neon Postgres.

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

Agentic Task Quality

Before editing, dev-task requires a task contract: stable acceptance-criterion IDs, evidence oracles, intended scope and consumers, external-effect boundaries, and stop conditions. Use the deterministic impact router to ground it:

Terminal window
go run scripts/agent_impact.go -path apps/brain/src/example.ts -strict
go run scripts/agent_impact.go -changed -strict

The first command predicts guides, consumers, risk, and checks for intended paths. The second fails when a changed path under an enforced repository root is unmapped. The router defines a minimum verification floor; task-specific risk can require more evidence.

The vendor-neutral suite in .agents/evals/single-shot.json covers contracts, migrations, billing, UI, containers, docs, integrations, ambiguity, and unsafe requests. CI validates its schema and routing references without spending model tokens:

Terminal window
make check-agent-quality

After a calibrated single-shot trial, grade its JSON result with:

Terminal window
go run scripts/check_agent_evals.go -result /path/to/result.json

Trial execution is intentionally outside required PR CI. The grader requires the expected decision, in-scope paths, acceptance evidence, passing checks, no unauthorized effects, and a completed independent review with no unresolved Critical or Important findings.

The grader recomputes impact rules and required checks from changed paths. Each check record must match the manifest command and include its working directory, zero exit code, and captured-output evidence. This is structural validation, not cryptographic provenance: a trusted trial runner or reviewer must collect the result; the model under evaluation must not grade its own claims.

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
make check-agent-quality