Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (73 loc) · 4.52 KB

AGENTS.md

File metadata and controls

81 lines (73 loc) · 4.52 KB
Raw

FlyPython repository guide

Mission

This repository is the community-maintained source for building good Python products in the AI-coding era. It is not a website. Keep flypython.com focused on presentation, discovery, and conversion; keep this repository focused on practical guides, playbooks, runnable examples, reusable templates, reviewed catalog data, and stable public JSON contracts.

Content rules

  • Prefer official documentation and primary sources.
  • Keep first-party Python engineering and AI-coding guidance specific, testable, and honest about what automation can and cannot prove.
  • Every catalog entry must include a stable ID, path, path-local order, source type, level, rationale, review date, status, and any key or safety requirements.
  • Do not call a project production-ready without current maintenance, licensing, security, and adoption evidence.
  • Do not use an LLM or web-search API to generate resource descriptions. Descriptions and classifications require human review.
  • Keep English and Chinese website output generated from the same canonical resource data. Do not hand-copy catalog content into website source files.
  • Keep paired English and Chinese first-party guides aligned in scope, version, review date, and factual meaning. All content (guides, playbooks, examples, courses, radar entries) ships EN+ZH in the same change.
  • Governance documents (AGENTS.md, CONTRIBUTING.md, docs/CONSUMING.md, docs/CURATION_POLICY.md, docs/REPO_TO_WEBSITE.md) are English-canonical. Version plans (docs/repo-plan-*.md) are maintained in Chinese by owner decision (2026-09-12); their English history stays in git.
  • Add first-party guides, playbooks, and courses to content-manifest.json; keep each locale pair aligned and verify its source checksum.
  • Courses live one folder per course under courses/<slug>/ and are taught by an AI coding agent from the files themselves: COURSE.md (metadata plus the teaching contract: audience, prerequisites, exact tool and version, lesson order, teaching-style rules, when to stop, how to use verify.py, and what the course does not cover) with id: course-<slug> and badge frontmatter, lessons/L01.md with L01_cn.md pairs (objective, exercise, checkpoint, expected evidence), scenario/ data files for each skin, TASK.md/TASK_cn.md (task contract), starter/ and solution/ runnable pairs, a self-contained verify.py that fails on starter and passes on solution, exposes deterministic claim codes through verify.py progress (five checkpoints), and runs on the standard library unless the course ships its own requirements.txt (as the pandas/matplotlib data-analysis courses do), and REVIEW.md recording the maintainer run-through (date, tool, version, observed agent deviations). A course is incomplete until every lesson ships EN+ZH in the same change; COURSE.md must name the exact tool version it was taught with, and a tool major release triggers re-review. Never claim guaranteed learning outcomes.
  • Treat HTTP 403, 429, and transient 5xx responses as review-needed states, not automatic proof that a resource is broken.

Change workflow

  • Work on a feature branch and preserve unrelated contributor changes.
  • Run the repository validation workflow before committing.
  • Regenerate catalog.json and radar.json after source changes and verify them with python tools/export_catalog.py --check --target both.
  • Regenerate both README catalog indexes and the Project Radar table, then verify them with python tools/render_readmes.py --check.
  • Regenerate content-manifest.json and verify it with python tools/build_content_manifest.py --check.
  • Verify every runnable example with python tools/verify_examples.py, every course folder with python tools/verify_courses.py, and every learning path with python tools/verify_paths.py.
  • Website consumers must pin a full repository commit and verify the catalog checksum. Do not make production builds depend on a moving branch.
  • Keep external-link checks read-only, rate-limited, retryable, and blocked from private or loopback network targets.
  • Do not add API keys, tokens, analytics IDs, or generated reports to git.
  • After merge, verify the immutable raw catalog.json. Verify flypython.com only after a separate, deliberate consumer-version update.

Review priorities

  1. Content accuracy and source quality.
  2. Deterministic export and bilingual parity.
  3. Schema, consumer-contract, and safe link checks.
  4. Clear contribution and licensing boundaries.