Add `AGENTS.md` guidance for AI coding agents, at the root and in the folders they change most

オープン
#3,210 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
35/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
静か
技術スタック
css, git, javascript, markdown, python

調査の方向性

Start with the root README.md, CONTRIBUTING.md, the Guide's developer chapters, and the README in each folder the issue names, then read commit #3148 as the one-feature-several-surfaces template. Write the eight AGENTS.md files and a root CLAUDE.md pointer, add CLAUDE.local.md to .gitignore, and run each listed command once. The issue asks for the shape to be agreed before any pull request, so confirm that with the maintainers first.

索引モデルが issue の本文から書いたものです。

説明

Follows the pretext-dev thread "Claude skill for pretext authoring" (https://groups.google.com/g/pretext-dev/c/0D90duVchZg), where a root AGENTS.md was proposed and I offered to write it. This issue records what the files would contain and how they would be organized, so the shape is agreed before the pull request.

AGENTS.md is the file format that AI coding agents (Codex, Cursor, GitHub Copilot and others, per https://agents.md) read for repository-specific instructions. Claude Code reads CLAUDE.md instead, so the pull request also adds a root CLAUDE.md whose whole content is a pointer to AGENTS.md. An agent reads the root file plus the file in whichever directory it is editing, so the folder files can be short and specific.

Audience. These files are for anyone, human or agent, changing the PreTeXt toolchain itself: stylesheets, schema, the Python script, CSS and JavaScript, the Guide, the sample documents. Guidance for authors writing a book in PreTeXt is a different deliverable (a skill leaning on the schema, the sample documents and validation, as suggested in the thread) and is out of scope here.

Principle: link, do not duplicate. The repository already has 45 README.md files, and they answer "what is this folder" well. What no file answers today is "what else must change when I change this, and how do I check it." Each AGENTS.md carries only that second kind of fact and links to the README for the first. Everything in them is traceable to an existing README, a chapter of the Guide, or the git history; nothing is invented for the occasion. Version minimums follow the same rule: the files point to the README or package.json that states each one, rather than restating a number.

Proposed files. Eight AGENTS.md, each under about 80 lines, the root under 120.

File Carries what is written down nowhere else
AGENTS.md Tool prerequisites; the multi-surface change pattern; commit and branch contract; which files are generated and never hand-edited; how to verify a change; pointers to CONTRIBUTING.md, the Guide's developer chapters, legal/copyright-holders.md
xsl/AGENTS.md XSLT 1.0 with EXSLT only, libxslt (through lxml in pretext/pretext) as reference processor; xsl/tests for text utilities; the linear import chain and the -common naming rule; PTX:BUG: versus PTX:WARNING: messages; copyright header on new files; a change to publisher-variables.xsl pairs with schema/publication-schema.xml
schema/AGENTS.md Only pretext.xml and publication-schema.xml are edited; .rnc and .rng are regenerated with xsltproc and trang and committed with the schema change; build.sh hard-codes a path; pretext-dev must stay purely additive
pretext/AGENTS.md Python minimum as stated in README.md; no automated test suite; other tools such as the CLI import this package, so public signatures are an interface; one-way import graph out of common.py; how a new generated-asset type threads through xsl/extract-*.xsl, lib/pretext.py, component_dirs and the -c vocabulary; copy pretext.cfg to user/, never edit it
css/AGENTS.md contributors edit sources only and never commit css/dist, which the maintainer regenerates when merging; a new theme or theme option also needs the option table in xsl/publisher-variables.xsl; examples/custom-theming is the smoke test; components are shared, targets are owned
js/AGENTS.md js/dist is handled likewise; prism/, diagcess/ and jQuery are vendored; bundle order in pretext-core.js is deliberate; other tools such as the CLI consume dist as-is
examples/AGENTS.md sample-article gains an example for every new feature; minimal stays small and is for isolating bugs; examples track their generated assets, committed in every format their builds use; which examples carry their own toolchain (webwork, pug, sample-book/gdpractice)
doc/guide/AGENTS.md Where a new element or publisher option is documented (Overview plus Topics; the Publication File reference plus the relevant Publisher chapter), from developer/coding.xml; elaborate examples belong in the Showcase Article, not the Guide; generated/ is build output

Not proposed: script/, journals/, fonts/, legal/. Their READMEs already state the rules; the root file points at them.

The worked example. PR #3148 (SVG favicon) is the template the root file uses for "one feature, several surfaces":

HTML: add SVG option for favicon-scheme
Publisher variables: add svg favicon option
Schema: add publisher option for SVG favicon
Sample article: change favicon to SVG
Guide: document SVG favicon option

The same pattern recurs across the last two years of history (Beamer options, GeoGebra play button, DoenetML, FITB), so it is stated as the norm, alongside the commit-subject convention it illustrates: Area: lowercase description, no period, one line, XML names in double quotes.

Verification. There is no CI in this repository, so the root file says what checking a change means here. Development runs through the pretext/pretext script, which uses the checkout's own stylesheets; the separate pretext-cli is not a development tool, so the files give no pretext build instructions:

  • validate with pretext/pretext -V, which resolves version support in assembly and then runs jing against both schema/pretext-dev.rng and schema/pretext.rng
  • build with pretext/pretext -c doc
  • regenerate the schema with xsltproc and trang
  • rebuild css/dist and js/dist locally to check a source change.

Each command is run once before it goes in the file.

Personal layers. Andrew's concern in the thread, that a committed file leaves no room for personal instructions, is handled by the tools rather than by this repository: Codex reads ~/.codex/AGENTS.md, Claude Code reads ~/.claude/CLAUDE.md, and Claude Code also reads a per-checkout CLAUDE.local.md. The pull request adds CLAUDE.local.md to .gitignore and the root CLAUDE.md says so in one line. The committed files stay canonical and tool-neutral.

Out of scope. An author-facing skill; any CI configuration; a release-notes file (removed deliberately in favor of the history).

Suggested shape: one pull request, one commit per file so each surface reviews on its own, no other changes riding along.

Claude Fable 5.1, acting as a coding assistant for Rick Roesler

主要言語
XSLT
スター
466
フォーク
251
平均マージ
4分
マージ済み PR(30日)
13

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

PreTeXtBook/pretext のほかの issue

PreTeXtBook/pretext の issue をすべて見る

似ている issue

DevTools の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。