docs: improve AI agent instructions and dev workflow guidance [skip ci] (#8284) [skip ci]

[rfay]

The Issue

AI agent instructions in CLAUDE.md and AGENTS.md had gaps: no allow permissions for common safe operations, no guidance on using upstream/main for PR comparisons, and the make staticrequired hook behavior wasn't clearly documented.

How This PR Solves The Issue

.claude/settings.json — add allow permissions:

• curl to github.com, raw.githubusercontent.com, buildkite.com
• Read-only gh subcommands: issue/pr/run list, view, checks, diff, status
• make*, go test*, gofmt*, ls*

These are safe, frequently used operations that shouldn't require manual approval on every invocation.

CLAUDE.md and AGENTS.md — upstream/main comparison guidance:

When generating diffs for a PR, prefer upstream/main as the base if the remote exists, fall back to origin/main. Local main may be stale. Not all developers use an upstream remote, so the guidance handles both cases gracefully.

CLAUDE.md — clarify make staticrequired hook behavior:

Made explicit that a PreToolUse hook in .claude/settings.json runs make staticrequired automatically before every git commit, and that gofmt/markdownlint --fix run via PostToolUse hooks after edits.

Note on CLAUDE.md vs AGENTS.md:

Claude Code now reads both CLAUDE.md and AGENTS.md. We are not consolidating them at this time because AGENTS.md serves other AI tools (Codex, Gemini, etc.) and the two files have meaningfully different audiences. Consolidation would be worth revisiting if the content continues to diverge in maintenance cost.

Manual Testing Instructions

1. Open repo in Claude Code
2. Verify make, go test, ls, and gh pr list no longer prompt for approval
3. Verify curl https://api.github.com/... no longer prompts for approval
4. Check that git commit still triggers make staticrequired via the hook

Automated Testing Overview

Documentation and config only — no code changes. Markdown linting passes.

Release/Deployment Notes

No impact on DDEV functionality.

[jonesrussell]

Review by Claude Code

Reviewed the three changed files (.claude/settings.json, CLAUDE.md, AGENTS.md). The documentation improvements are solid — notably correcting the inaccurate "PreToolUse and PostToolUse" description to correctly say PostToolUse for gofmt/markdownlint. The PreToolUse hook description for make staticrequired is verified accurate against the actual settings.json config.

A few things worth considering:

---

curl allow patterns match arbitrary domains

The patterns like Bash(curl*github.com*) will match any curl invocation where github.com appears anywhere in the argument string — including as a query parameter or path fragment on a different host (e.g., curl https://evil.com/?ref=github.com).

Consider anchoring to the scheme + domain:

"Bash(curl https://github.com*)"
"Bash(curl https://raw.githubusercontent.com*)"
"Bash(curl https://buildkite.com*)"

---

git fetch upstream 2>/dev/null silently swallows real errors

In both CLAUDE.md and AGENTS.md, the pattern:

git fetch upstream 2>/dev/null || git fetch origin

If upstream exists but fetch fails for a real reason (expired SSH key, network timeout), stderr is suppressed and the fallback silently fetches origin instead. The agent then diffs against a potentially wrong base with no warning.

Separating remote detection from fetching would be more robust:

if git remote get-url upstream >/dev/null 2>&1; then
  git fetch upstream
else
  git fetch origin
fi

---

Minor pattern concerns in the allow/deny lists

• Bash(tr*) — matches truncate as well as tr. Could silently allow truncate -s 0 <file>.
• Bash(git branch*) — matches git branch -D (force delete). If the intent is read-only listing, consider denying Bash(git branch -D*) and Bash(git branch -d*).
• Bash(find*-exec rm*) deny — doesn't catch find -exec /usr/bin/rm or find -exec unlink. Consider broadening to Bash(find*-exec*) if the goal is blocking destructive find operations.

---

Duplicated section across CLAUDE.md and AGENTS.md

The "Comparing Against Upstream" section is word-for-word identical in both files. The PR body explains why both files exist (different audiences), which makes sense. A small <!-- Keep in sync with AGENTS.md --> comment in each might help prevent drift over time.

---

Overall this is a useful improvement to the AI agent workflow. The documentation accuracy fixes are a clear win. The permission patterns are a good idea — the suggestions above are about tightening the globs rather than questioning the approach.

[stasadev]

Looks good to me.

[rfay]

Think these are probably "good enough" for now.