Skip to content

AGENTS.md

Latest commit

 

History

History
143 lines (111 loc) · 6.53 KB

AGENTS.md

File metadata and controls

143 lines (111 loc) · 6.53 KB
Raw

AGENTS.md — AI-assisted contributions to CORAL

CORAL is itself infrastructure for running autonomous coding agents, so we fully expect contributors to use Claude Code, Codex, Cursor, Kiro, OpenCode, or other agents while developing changes. This document sets the ground rules.

These rules apply to any PR where an AI coding agent meaningfully wrote, refactored, or generated code, tests, or docs. If you are not sure whether your workflow counts, it does — read on.

TL;DR

  • All PRs target the dev branch, never main (see CONTRIBUTING.md).
  • Release tags point to the promoted dev commit, not the main merge commit; do not add main-only release changes or routine main-to-dev sync PRs.
  • A human author must read every changed line and be able to defend the design end-to-end.
  • No drive-by mechanical PRs (lone typo fixes, single-line style nits, batch reformat across the repo).
  • Don't open duplicate PRs against the same issue. Check first.
  • Keep AGENTS.md in sync with CLAUDE.md when project guidance changes.
  • Don't dump raw agent transcripts into the PR description. Summarize.

1. Human accountability

  • Pure agent-authored PRs are not accepted. A human must understand the change, review every line, and respond to review comments themselves — not by piping reviewer questions back into an agent and posting the reply.
  • The submitting human is responsible for:
    • Correctness of the diff,
    • Running tests + lint locally before pushing,
    • Following up on review feedback,
    • Any regressions introduced by the change.
  • "An agent wrote it" is not an explanation for design choices in review.

2. Scope discipline

  • Bundle agent output with substantive work. Don't open standalone PRs for things like:
    • a single typo fix,
    • one isolated ruff-style nit,
    • reformatting a file the agent happened to touch,
    • changing a comment without changing behavior. Roll these into a larger PR that actually does something, or batch many of them into one explicit cleanup PR with a clear scope statement.
  • One concern per PR. If your agent generated a refactor and a bug fix in the same run, split them.
  • Don't reformat the world. Repo-wide formatting / import-sorting / rename-the-variable PRs are a "no" unless coordinated with maintainers first (and then they go on .git-blame-ignore-revs).

3. Duplicate-work checks

Before opening a PR, verify nobody is already on it:

gh issue view <issue_number> --repo Human-Agent-Society/CORAL --comments
gh pr list --repo Human-Agent-Society/CORAL --state open --search "<issue_number> in:body"
gh pr list --repo Human-Agent-Society/CORAL --state open --search "<short keywords>"

If an open PR is already in flight:

  • If it looks stalled, comment there to check in. Don't open a parallel PR.
  • If your approach is materially different, file an issue (or comment on the existing one) explaining the difference before submitting.

4. Keep agent guidance synchronized

CLAUDE.md is the detailed project guide used by Claude Code, and AGENTS.md is the cross-agent contribution guide. Keep them consistent:

  • If you update CLAUDE.md with project structure, workflow, command, testing, PR, or agent-specific guidance, check whether AGENTS.md needs the same rule or a tool-agnostic version of it.
  • If you update AGENTS.md with contribution rules that should affect Claude Code sessions, check whether CLAUDE.md needs the corresponding detail.
  • If only one file should change, say why in the PR description.

5. Disclosure in PR descriptions

If an agent did the bulk of the writing, say so plainly. We don't penalize agent-assisted PRs — we just want the review framed correctly.

Use .github/PULL_REQUEST_TEMPLATE.md as-is. Do not replace it with a custom short summary. In particular:

  • Keep the Motivation, Changes, Test plan, Affected areas, and Checklist sections.
  • Tick every affected area that applies.
  • Tick checklist items only when they are true. If the full-suite template commands were not run, leave those boxes unchecked and list the narrower commands you did run in Test plan.
  • Reference issues in the body (Closes #123) when applicable.

A minimal disclosure looks like:

Authored with assistance from <tool>. I read every changed line, ran the tests below locally, and verified the behavior described in the test plan.

What not to do:

  • Don't paste raw agent transcripts, multi-thousand-line reasoning traces, or hidden "system prompt" blocks. Summarize the design instead.
  • Don't fabricate test results. If you didn't run it, don't claim you did.
  • Don't link to private agent sessions. Reviewers can't follow those.

6. CORAL-specific gotchas for agents

These tend to bite AI-generated PRs in this repo specifically:

  • .coral/private/ is hidden from agents at runtime. Don't write code that assumes agents can read grader internals (answer keys, hidden test inputs, grader source). See coral/workspace/project.py.
  • The grader runs in its own venv (.coral/private/grader_venv/). Adding a dep to pyproject.toml does not put it on the grader's path — use grader.setup in task.yaml instead.
  • Grader output must not write to codebase_path. The daemon force- removes that directory after grading. Anything the grader wants to persist goes through ScoreBundle or self.private_dir.
  • Score direction matters. Task.maximize controls which way is better — agents often flip this. Double-check against existing examples.
  • Don't commit hidden answers under seed/. Anything in seed/ ends up in the agent's worktree, visible to the running agent.
  • CORAL.md is generated by coral/template/coral_md.py — don't hand- edit the rendered file in a worktree, edit the template instead.

If you're adding a new task, the coral-new-task skill walks through these in detail. For framework-level changes, see coral-extend; for debugging, coral-debug.

7. Reviewer guidance

Reviewers should:

  • Flag PRs that look like raw agent output without human review (telltale signs: unrelated drive-by changes, invented APIs, broken imports, fake citations, "test plan" sections that don't match the diff).
  • Ask the human author — not the agent — to explain non-obvious choices.
  • Close low-value mechanical PRs with a pointer to this document.

By submitting a PR you confirm you've read CONTRIBUTING.md and, if applicable, this document.