Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (67 loc) · 4.19 KB

AGENTS.md

File metadata and controls

75 lines (67 loc) · 4.19 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), 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, stdlib-only verify.py that fails on starter and passes on solution, 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 and every course folder with python tools/verify_courses.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.