From bc3e7a08cd7b46b22061b3453283ecd00964470d Mon Sep 17 00:00:00 2001 From: Vinta Chen Date: Sun, 16 Aug 2026 02:45:31 +0800 Subject: [PATCH] docs: condense AGENTS.md and CLAUDE.md for progressive disclosure Trim repository overview and structure sections into a brief intro plus focused Entry Rules and Gotchas sections, dropping restated CONTRIBUTING.md content and Makefile/pyproject boilerplate. Co-Authored-By: Claude --- AGENTS.md | 33 ++++++++------------------------- CLAUDE.md | 33 ++++++++------------------------- 2 files changed, 16 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 646889dc..af55f4d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,32 +1,15 @@ # AGENTS.md -## Repository Overview +An opinionated shortlist of Python frameworks, libraries, tools, and resources, published at [awesome-python.com](https://awesome-python.com/). README.md is the single source of truth for catalog entries and README sponsor placements; `website/` renders it into the static site. -An opinionated list of Python frameworks, libraries, tools, and resources. Published at [awesome-python.com](https://awesome-python.com/). +## Entry Rules -## Entry Guidelines +[CONTRIBUTING.md](CONTRIBUTING.md) holds the admission rules, quality requirements, rejection rules, entry format, and ordering. Apply it whenever adding or removing an entry — direct commits included, not only PR reviews. -**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for admission rules, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly. +- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Training-data recollections are not evidence; label anything unverifiable as a judgment call. +- One entry per commit when adding or deleting entries. Exceptions: a prune sweep is one commit per section, its body listing each removal with its reason; format, wording, or categorization changes may be bundled. +- Sponsor placement never influences which projects get listed — see [SPONSORSHIP.md](SPONSORSHIP.md). `website/templates/sponsorship.html` separately defines the sponsorship content on the published website page. -## Structure +## Gotchas -- **README.md**: Source of truth for catalog entries and README sponsor placements. Hierarchical categories; entries ordered per the Key Rules below. -- **CONTRIBUTING.md**: Submission guidelines and review criteria. -- **SPONSORSHIP.md**: Sponsor tiers, placement rules, and the editorial-independence policy. `website/templates/sponsorship.html` separately defines which sponsorship content appears on the published website page. -- **website/**: Static site generator that builds awesome-python.com from README.md. - - `build.py`: Parses README.md and renders HTML via Jinja2 templates. - - `fetch_github_stars.py`: Fetches star counts into `website/data/`. - - `readme_parser.py`: Markdown-to-structured-data parser. - - `templates/`, `static/`: Jinja2 templates and CSS/JS assets. - - `tests/`: Pytest tests for the build pipeline. -- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`. On machines with only Python 3.14, prefix uv-based targets with `UV_PYTHON=3.13` (watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`). -- **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13. - -## Key Rules - -- Ordering within a use case: obvious choices first, then challengers, each tier by PyPI downloads/month descending; no-signal entries last in tier, alphabetically. See CONTRIBUTING.md. -- A shortlist, not a catalog: per use case, up to 3 obvious choices plus up to 2 challengers, hard maximum 5. -- One project per PR. -- One entry per commit when adding or deleting entries. Exception: a prune sweep is one commit per section, its body listing each removal with its reason. Format, wording, or categorization changes across multiple entries may be bundled in a single commit. -- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Training-data recollections alone are not evidence; verify before stating, and label anything unverifiable as a judgment call. -- README.md is the source of truth for catalog entries and README sponsor placements; treat `SPONSORSHIP.md` and `website/templates/sponsorship.html` as separate sponsorship content surfaces. +- On machines with only Python 3.14, prefix uv-based make targets with `UV_PYTHON=3.13` — watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`. diff --git a/CLAUDE.md b/CLAUDE.md index 52b9391c..67117dd9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,32 +1,15 @@ # CLAUDE.md -## Repository Overview +An opinionated shortlist of Python frameworks, libraries, tools, and resources, published at [awesome-python.com](https://awesome-python.com/). README.md is the single source of content truth; `website/` renders it into the static site. -An opinionated list of Python frameworks, libraries, tools, and resources. Published at [awesome-python.com](https://awesome-python.com/). +## Entry Rules -## Entry Guidelines +[CONTRIBUTING.md](CONTRIBUTING.md) holds the admission rules, quality requirements, rejection rules, entry format, and ordering. Apply it whenever adding or removing an entry — direct commits included, not only PR reviews. -**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for admission rules, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly. +- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Training-data recollections are not evidence; label anything unverifiable as a judgment call. +- One entry per commit when adding or deleting entries. Exceptions: a prune sweep is one commit per section, its body listing each removal with its reason; format, wording, or categorization changes may be bundled. +- Sponsor placement never influences which projects get listed — see [SPONSORSHIP.md](SPONSORSHIP.md). -## Structure +## Gotchas -- **README.md**: Source of truth. Hierarchical categories; entries ordered per the Key Rules below. -- **CONTRIBUTING.md**: Submission guidelines and review criteria. -- **SPONSORSHIP.md**: Sponsor tiers, placement rules, and the editorial-independence policy. Sponsor content sits in the README header and must never influence which projects get listed. -- **website/**: Static site generator that builds awesome-python.com from README.md. - - `build.py`: Parses README.md and renders HTML via Jinja2 templates. - - `fetch_github_stars.py`: Fetches star counts into `website/data/`. - - `readme_parser.py`: Markdown-to-structured-data parser. - - `templates/`, `static/`: Jinja2 templates and CSS/JS assets. - - `tests/`: Pytest tests for the build pipeline. -- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`. On machines with only Python 3.14, prefix uv-based targets with `UV_PYTHON=3.13` (watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`). -- **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13. - -## Key Rules - -- Ordering within a use case: obvious choices first, then challengers, each tier by PyPI downloads/month descending; no-signal entries last in tier, alphabetically. See CONTRIBUTING.md. -- A shortlist, not a catalog: per use case, up to 3 obvious choices plus up to 2 challengers, hard maximum 5. -- One project per PR. -- One entry per commit when adding or deleting entries. Exception: a prune sweep is one commit per section, its body listing each removal with its reason. Format, wording, or categorization changes across multiple entries may be bundled in a single commit. -- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Training-data recollections alone are not evidence; verify before stating, and label anything unverifiable as a judgment call. -- README.md is the single source of content truth. +- On machines with only Python 3.14, prefix uv-based make targets with `UV_PYTHON=3.13` — watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`.