From 1b5a0c2a3c151748e741095fcd1ba885f4110333 Mon Sep 17 00:00:00 2001
From: Vinta Chen <vinta.chen@gmail.com>
Date: Sun, 22 Mar 2026 16:41:42 +0800
Subject: [PATCH] docs(claude): expand project structure and entry format docs

Documents the website/ build pipeline, Makefile targets, pyproject.toml
tooling, and tightens the entry format example and key rules.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 81d13417..15b939a8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,31 +2,36 @@
 
 ## Repository Overview
 
-This is the awesome-python repository - a curated list of Python frameworks, libraries, software and resources. The repository serves as a comprehensive directory about Python ecosystem.
+A curated list of awesome Python frameworks, libraries, software and resources. Published at [awesome-python.com](https://awesome-python.com/).
 
 ## PR Review Guidelines
 
-**For all PR review tasks, refer to [CONTRIBUTING.md](CONTRIBUTING.md)** which contains:
+**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for acceptance criteria, quality requirements, rejection rules, and entry format.
 
-- Acceptance criteria (Industry Standard, Rising Star, Hidden Gem)
-- Quality requirements
-- Automatic rejection criteria
-- Entry format reference
-- PR description template
+## Structure
 
-## Architecture & Structure
+- **README.md**: Source of truth. Hierarchical categories with alphabetically ordered entries.
+- **CONTRIBUTING.md**: Submission guidelines and review criteria.
+- **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 fetch_github_stars`.
+- **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13.
 
-The repository follows a single-file architecture:
+## Entry Format
 
-- **README.md**: All content in hierarchical structure (categories, subcategories, entries)
-- **CONTRIBUTING.md**: Submission guidelines and review criteria
-- **sort.py**: Script to enforce alphabetical ordering
+```markdown
+- [pypi-name](https://github.com/owner/repo) - Description ending with period.
+```
 
-Entry format: `* [project-name](url) - Concise description ending with period.`
+Use PyPI package name as display name. Use GitHub URLs when available.
 
-## Key Considerations
+## Key Rules
 
-- This is a curated list, not a code project
-- Quality over quantity - only "awesome" projects
-- Alphabetical ordering within categories is mandatory
-- README.md is the source of truth for all content
+- Alphabetical ordering within categories is mandatory.
+- Quality over quantity. Only "awesome" projects.
+- One project per PR.
+- README.md is the single source of content truth.