Skip to content

AGENTS.md

Latest commit

 

History

History
147 lines (108 loc) · 6.19 KB

AGENTS.md

File metadata and controls

147 lines (108 loc) · 6.19 KB
Raw

AGENTS.md

nanoPyCodeAgent — a nano code agent built from scratch in pure Python.

This is the shared project instruction file for coding agents. Codex reads AGENTS.md; Claude Code reads CLAUDE.md, a symlink to this file.

Skills

Project skills live in .agents/skills/ and are auto-discovered by Codex and pi (.agents/skills/**/SKILL.md); Claude Code discovers them via .claude/skills (a symlink to .agents/skills). Use a skill by stating intent — the agent loads the matching one:

  • Landing a PR (everyday, no release) — merge a feature/bugfix PR into main: .agents/skills/land-pr/SKILL.md
  • Releasing (cut a version, publish to PyPI + GitHub): .agents/skills/release/SKILL.md

See docs/RELEASING.md for the release process and prerequisites.

Benchmarks

For new Harbor benchmark runs, use the standard workflow from the repository root: uv run --project benchmarks/harbor python -m harbor_adapter run --config <config.json>. See benchmarks/harbor/README.md for configuration, verified APT cache import, and the --install-only dependency preflight option.

  • Do not create per-job adapter copies or ad hoc bootstrap scripts. Add reusable fixes and reviewed task-revision profiles to benchmarks/harbor with tests.
  • Preserve task images, package sources, and official test scripts. Cache hits must match the current package index's filename, size, and SHA256 digest.
  • Run dependency preflight before model work when a task has a registered profile. Record unsupported profiles explicitly; do not claim they passed.
  • Keep setup failures and verifier errors separate from scored failures. Only verifier timeouts may retry, at most three total attempts using the same agent output and the task's original per-attempt time limit.

Language

Write everything in English by default — source code (identifiers, comments, string literals), commit messages, PR titles/descriptions, changelog entries, and Markdown documentation.

The only exception is documentation explicitly designated as Chinese:

  • README.zh-CN.md and any other *.zh-CN.* file.
  • Files under a zh-CN/ directory (e.g. docs/dev_notes/zh-CN/).
  • Design specs under docs/superpowers/specs/ — the prose may be Chinese for review convenience, but the deliverables the spec produces (code under src/, tests, and any English documentation) remain English.
  • Any document with an explicit requirement to be written in Chinese.

Everything outside that list — including code under src/, this file, and all other docs — is English.

Do not label a document as hand-written unless its contents are actually authored and maintained by humans. For agent-authored source-of-truth documents, use wording such as Chinese source instead.

Bilingual benchmark reports

Harbor benchmark reports MUST be generated and maintained in both languages:

  • benchmarks/harbor/reports/en/ contains the English reports.
  • benchmarks/harbor/reports/zh-CN/ contains complete Simplified Chinese translations with the same filenames as their English counterparts.
  • When creating or updating a report, generate or refresh both versions in the same change. Preserve all results, caveats, tables, evidence references, identifiers, commands, and hashes across the pair; do not substitute a summary for a full translation.
  • Keep relative links valid after moving or translating reports. English documents should link to English reports, and Chinese documents to Chinese reports; links between reports should stay in the current language.
  • Before opening or landing a PR that changes reports, verify that both language versions are present and in sync, and report that status to the user.

Bilingual research notes

Research notes are bilingual:

  • docs/research/zh-CN/ contains the Chinese sources of truth.
  • docs/research/en/ contains English versions generated from the Chinese sources; regenerate the whole corresponding file instead of hand-editing it.

When a change to a Chinese research source is headed into a pull request, the agent MUST remind the user that the corresponding English version also needs to be translated or refreshed. Before opening or landing the PR, report whether the English version is in sync, even when it has already been updated.

Commits & PRs

Branch and pull request workflow

All non-release changes MUST be made on a dedicated branch and merged into main through a GitHub pull request.

  • Before modifying repository files, agents MUST verify that the current branch is not main. If it is main, create or switch to a dedicated branch first.
  • Agents MUST NOT commit directly to main or push non-release commits to origin/main.
  • Open a pull request targeting main, and use the land-pr skill to merge it. Do not merge without the skill's mandatory maintainer confirmation.
  • If work was accidentally started on main, move the changes to a dedicated branch before committing or pushing them.

The sole exception is the release workflow in .agents/skills/release/SKILL.md. Only when the maintainer explicitly requests a release may that skill commit and push its release-only changes directly to main, and only after its mandatory confirmation gate. Documentation, chores, hotfixes, and all other work still require a branch and pull request.

Commit and PR title format

All agents working in this repo MUST follow Conventional Commits 1.0.0 for commit messages and PR titles (squash-merge often uses the PR title as the commit subject).

Format:

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Rules:

  • Description: imperative mood, lowercase, no trailing period.
  • Breaking changes: add ! after the type/scope and/or include a BREAKING CHANGE: footer.
  • Separate the optional body and footer(s) from the description with a blank line.

Examples:

  • feat: add streaming output to the agent loop
  • fix(parser): handle empty tool-call arguments
  • docs: require Conventional Commits in AGENTS.md
  • refactor!: drop Python 3.9 support (breaking change)