docs: add a contributor and coding-agent guide - #76
Conversation
Records the process the user docs do not carry: the build-policy defaults that must not be relaxed to get a build through, the dependency update order, and the rename-script invariant that the template workflow enforces. Claude Code reads CLAUDE.md rather than AGENTS.md, so the symlink points it at the same file.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 83a49d80cc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1dcb25461f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
CLAUDE.md becomes a regular file importing AGENTS.md, the alternative the Claude Code documentation gives for the symlink. That removes the only tracked symlink, so PRETTIER_SOURCES and MARKDOWN_SOURCES go back to a plain git ls-files. The import also survives a Windows checkout. Git without symlink support writes the link target as file content, which would leave a generated project with a CLAUDE.md containing the string AGENTS.md.
1 participant
Summary
This repository had no
AGENTS.md, so an agent working here started from the README and had to infer the rest. Since the repository is a template, that gap propagates to every project generated from it.The guide records the process the user docs do not carry, and links into
docs/development.mdrather than restating it:conanfile.pythenmake lockthen verify then commit both, and that a lock regenerated without a pin change is churn..github/workflows/template.ymlrenames the template in CI and then builds, tests, and runs the result, so a new file carrying the project name has to teachscripts/rename.pyabout it in the same change or that workflow fails.CLAUDE.mdis a symlink toAGENTS.mdbecause Claude Code reads only the former.Test plan
markdownlint --config .markdownlint.json AGENTS.mdis cleanprettier --check AGENTS.mdreports the file already conformsdocs/development.mdanchor referenced resolves to a real headinggit ls-files -s CLAUDE.mdreports mode120000rename / ubuntu-latest / gcc, which is the one this change could plausibly affect