Add `AGENTS.md` guidance for AI coding agents, at the root and in the folders they change most
メンテナーはふだん 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 runsjingagainst bothschema/pretext-dev.rngandschema/pretext.rng - build with
pretext/pretext -c doc - regenerate the schema with
xsltprocandtrang - rebuild
css/distandjs/distlocally 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 を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
PreTeXtBook/pretext のほかの issue
-
The print preview leaves writing space short by the margins of hidden headers, footers and solutionsオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
PreTeXtBook/pretext#3329 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1〜3時間 初心者へのやさしさ 82/100
PreTeXtBook/pretext#3305 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
PreTeXtBook/pretext#3297 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
PreTeXtBook/pretext#3285 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
PreTeXtBook/pretext#3283 ·
メンテナーはふだん 1 日以内に返信
PreTeXtBook/pretext の issue をすべて見る
似ている issue
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 64/100
ScoopInstaller/Extras#19404 ·
メンテナーはふだん 1 日以内に返信
-
area: batch
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
inabagumi/shinju-date#7294 ·
メンテナーはふだん 1 日以内に返信
-
documentation
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
streaming-video-technology-alliance/common-media-library#700 ·
メンテナーはふだん 1 日以内に返信
-
bot:ai-assisted component:platform-js status:untriaged
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
midnightntwrk/platform-js#35 ·
-
could-have
難易度 1/5 1時間未満 初心者へのやさしさ 88/100