docs: add agent development guide

2026-07-02 11:43:04 +08:00
parent dfcfb68667
commit ace3804f74
1 changed files with 284 additions and 0 deletions
@@ -0,0 +1,284 @@
 # AGENTS.md
 ## Purpose
 This file defines how AI coding agents should work in this repository. It is an operating guide, not a product requirements document.
 Do not restate or replace the product specs here. Product requirements, UI decisions, technical decisions, and test expectations live in `docs/`.
 ## Source Of Truth
 Before implementation, read the relevant docs in this order:
 1. `docs/PRD.md`
 2. `docs/RequirementsDoc.md` (if it exists in the repository; skip if absent)
 3. `docs/FeatureSummary.md`
 4. `docs/DevelopmentPlan.md`
 5. `docs/Tasks.md`
 6. `docs/TDD.md`
 7. `docs/UIDesign.md`
 8. `docs/API-Spike-Xiaohongshu.md`
 9. `docs/API-Spike-Douyin.md`
 If `docs/review-*.md` files exist, read them after the corresponding source document.
 Review files contain corrections and clarifications that override ambiguous points
 in the source document. For example, read `review-Tasks-kiro.md` after `Tasks.md`.
 Use `docs/DevelopmentPlan.md` for architecture and technology choices. Use `docs/Tasks.md` for implementation sequencing. Use `docs/TDD.md` for test strategy. Use `docs/UIDesign.md` for page structure and UI behavior. Use the API Spike docs for platform field mapping and external API flow.
 If documents conflict or if the provided context is insufficient to make a decision,
 DO NOT guess or hallucinate. Stop execution immediately, summarize the conflict or
 information gap, cite the files involved, and ask the user for confirmation before
 implementing. This applies to all levels of conflict -- architecture, implementation
 details, naming conventions, and behavioral expectations alike.
 Never proceed with an assumption when the source documents are ambiguous or silent
 on a required decision.
 If you cannot find the answer in the listed documents and your own knowledge is
 uncertain, state explicitly: "I don't have enough context to decide this. Please
 provide [specific document or clarification]." Never fill gaps with invented behavior.
 ## Project Constraints
 - Build a lightweight MVP first.
 - Prefer a working end-to-end flow over broad incomplete features.
 - Keep the architecture aligned with the current plan: FastAPI, SQLite, SQLAlchemy, Jinja2 templates, simple CSS or Bootstrap, native JavaScript, and Docker Compose.
 - Do not introduce a frontend SPA framework, Redis, Celery, PostgreSQL, login system, scheduled jobs, or distributed workers unless the user explicitly changes the scope.
 - Do not commit real API keys, tokens, cookies, or private credentials.
 - Treat TikHub and AI providers as external dependencies that must be mocked in tests.
 - Background tasks run in a ThreadPoolExecutor thread, not in the async event loop.
  Use synchronous `httpx.Client` for all external HTTP calls in background tasks.
  Do not use `httpx.AsyncClient` or `await` in background task functions.
 - Reports are pre-generated after task completion and stored in the `reports` table.
  Page rendering and file exports must read from the same pre-generated report data.
  Do not compute statistics on-the-fly in page route handlers.
 - Task execution uses `ThreadPoolExecutor(max_workers=1)`. Only one task can run at
  a time. If a task with `status=running` already exists, reject new task creation
  with HTTP 400.
 ## MVP Discipline (Optimized for Speed)
 The constraints in §Project Constraints are always active regardless of timeline.
 This section provides prioritization guidance, not permission to skip P0 features
 defined in `docs/Tasks.md`.
 When the user asks for fast delivery, optimize for the earliest demonstrable slice.
 But you MUST deliver all P0 tasks defined in `docs/Tasks.md` §7 (T01-T23).
 Do NOT defer any P0 feature without explicit user confirmation.
 Items that may be deferred only with explicit user confirmation:
 - Playwright e2e tests (T23 Playwright portion only)
 - P1 optional tasks (docs/Tasks.md §9: auto-polling, JSON debug panel, progress bar)
 - Advanced UI polish (breadcrumbs, `<title>` naming, progress animations)
 Items that must NOT be deferred without explicit user confirmation:
 - Zombie task recovery (T05)
 - 429 exponential backoff (T07)
 - Comment pagination (T10)
 - AI retry and degradation (T13)
 - Report pre-generation (T14/T15/T16)
 - CSV/Markdown export (T20)
 - Docker Compose packaging (T22)
 Defer polish, scale, authentication, scheduling, and features not listed in
 `docs/Tasks.md` P0 scope. When in doubt about whether something is P0,
 check `docs/Tasks.md` -- it is the authoritative task list.
 ## Development Workflow
 For each task:
 1. Inspect the relevant docs and existing code.
 2. Identify the smallest useful implementation slice.
 3. Write tests BEFORE business logic for:
   - Data mapping and field transformation (platforms -> models)
   - AI JSON Schema validation and parsing
   - Report statistics calculation
   - Export formatting (CSV structure, Markdown structure)
   - State machine transitions (task status, analysis status)
   - Error degradation paths (retry exhaustion -> fallback behavior)
   For UI templates, route handler wiring, and configuration setup,
   write tests before or alongside implementation -- but never after.
   This is a hard rule from `docs/TDD.md` §2.1: "禁止先实现后补测试。"
 4. Implement the minimum code needed to pass the tests.
 5. Run focused verification commands.
 6. Report what changed, what was verified, and what remains.
 Keep changes scoped. Avoid unrelated refactors. If a file or design issue blocks the requested work, propose the smallest corrective change that serves the current goal.
 ### Error Handling Philosophy
 These principles are defined in `docs/DevelopmentPlan.md` §10 and `docs/TDD.md` §13.
 Apply them consistently across all implementations:
 - A single item failure must not crash the entire task. Isolate failures at the
  per-comment or per-content-item level.
 - External API failures (4xx/5xx) should be retried with exponential backoff
  (1s -> 2s -> 4s), then gracefully degraded with error recorded in the database.
 - AI analysis failures should be recorded per-comment via `ai_analysis_status=failed`
  and reflected in `analysis_success_rate`, not propagated as task-level failures.
 - Page rendering must never return HTTP 500 due to missing report data.
  Use default text or empty-state UI instead.
 - Each processing unit (content item, comment batch) should commit to the database
  independently. Do not hold a single transaction open for the entire task duration.
 ## Superpowers Workflow
 Superpowers are structured thinking modes available in certain AI coding environments
 (e.g., Codex). If the current environment does not support `superpowers:*` prefixes,
 apply the same cognitive sequence manually: brainstorm -> plan -> test-first -> implement
 -> debug -> verify.
 When superpowers skills are available, use them as the development process layer:
 - Use `superpowers:brainstorming` before unclear feature design, scope decisions, or behavior changes.
 - Use `superpowers:writing-plans` before substantial implementation.
 - Use `superpowers:test-driven-development` for business logic, data mapping, parsing, reporting, and bug fixes when practical.
 Before moving from implementation to the verification step:
 - Remove all placeholder comments (e.g., `# TODO: implement this`, `# FIXME`).
 - Remove all debugging print/console.log statements.
 - Ensure no commented-out code blocks remain unless they serve as documentation
  for a deliberate design decision (annotated with a reason).
 - Use `superpowers:systematic-debugging` before fixing failing behavior or unexpected test results.
 - Use `superpowers:verification-before-completion` before claiming work is complete.
 - Use `superpowers:requesting-code-review` for large changes or milestone completion.
 If the skills are unavailable, follow the same principles manually: clarify scope, write a short plan, test first where practical, debug from evidence, verify before completion, and keep commits focused.
 ## Multi-Agent Rules
 Use multiple agents only for independent work that can be reviewed and integrated by the main agent.
 Good parallel tasks:
 - Review docs for conflicts.
 - Investigate one platform API mapping.
 - Draft tests for one service.
 - Review UI behavior against `docs/UIDesign.md`.
 - Review implementation for bugs after a feature is complete.
 - Implementing two independent platform adapters (e.g., T08 Xiaohongshu and T09 Douyin).
 - Building two page templates that do not share data queries (e.g., T17 and T18).
 - Implementing export service (T20) while another agent works on template macros (T21).
 - Writing unit tests for module A while another agent implements module B that has no
  dependency on A.
 Avoid parallel agents for:
 - Editing the same core file at the same time.
 - Making competing architecture decisions.
 - Changing shared data models without one owner.
 - Implementing broad cross-cutting changes without an integration plan.
 The main agent remains responsible for final decisions, integration, verification, and Git commits.
 ## Testing And Verification
 Follow `docs/TDD.md`.
 Default verification targets:
 ```bash
 pytest tests/unit -q
 pytest tests/integration -q
 pytest tests/unit tests/integration -q
 curl -f http://localhost:8000/health
 ```
 Before claiming a milestone or task complete, run the coverage check:
 ```bash
 pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
 ```
 Target line coverage: 80% or above for the following modules:
 - `app/platforms/` (all platform adapters)
 - `app/services/ai_service.py`
 - `app/services/report_service.py`
 - `app/services/export_service.py`
 If coverage drops below 80% for these modules, add tests before proceeding.
 Use focused commands while developing, then run broader verification before completion. Do not rely on real TikHub or AI API calls for unit tests. Mock external HTTP calls and AI responses.
 For UI work, verify rendered pages manually or with browser automation when practical. Check that text does not overlap, core actions are visible, and the page follows `docs/UIDesign.md`.
 ## Git Workflow
 Use small, focused commits. One commit should represent one clear change.
 Recommended commit prefixes:
 - `docs:` documentation changes
 - `feat:` new user-visible functionality
 - `fix:` bug fixes
 - `test:` tests only
 - `chore:` maintenance, tooling, or project setup
 Before committing:
 ```bash
 git status --short
 git diff
 git diff --check
 ```
 Commit only files related to the current task. Do not revert unrelated user changes. Push only after the commit is verified and the user wants the branch updated remotely.
 ### Branch Strategy
 For single-agent development: work directly on `main` unless the user specifies
 a different branch.
 For multi-agent parallel development: each agent MUST operate on a separate Git
 branch derived from the current `main`. Branch naming convention:
 `agent/<agent-id>/<task-id>` (e.g., `agent/codex-1/T08`).
 Only the primary agent (or the user) may perform merges back to `main`.
 Before merging, the branch must pass all tests defined in §Testing And Verification.
 Never have two agents editing the same file on different branches simultaneously.
 If task dependencies require touching the same file, serialize the work.
 ## Safety Rules
 - Never store secrets in source files, docs, tests, fixtures, or commit messages.
 - Use `.env.example` for variable names only.
 - Keep raw external API responses only where the docs require them and avoid including private user data in fixtures.
 - In test fixtures, replace real usernames, avatar URLs, user IDs, and IP addresses
  with placeholder values (e.g., "test_user_001", "https://example.com/avatar.png",
  "user_id_placeholder_001"). Do not copy production API responses directly into
  fixture files without sanitization.
 - The `raw_data` JSON field in the database may contain user-generated content.
  When writing tests that assert on `raw_data`, use synthetic fixture data only.
 - If credentials are exposed during the conversation, remind the user to rotate or delete them.
 - Do not use destructive Git commands unless the user explicitly asks for them.
 ## Completion Standard
 A task is complete only when:
 1. The requested behavior or document exists.
 2. Relevant tests or checks have been run, or the reason they could not be run is stated.
 3. The work is scoped to the request.
 4. The final response explains the result in plain language.
 5. Any remaining risks or follow-up tasks are clearly named.
 6. If the completed task corresponds to a checkbox in `docs/Tasks.md`, mark it
   as done (change `- [ ]` to `- [x]`).
 7. The final response MUST explicitly state which tests were run and passed,
   which edge cases were verified or mocked, and any known limitations of the
   current implementation.
 ---
 ## Changelog
 | Date | Version | Changes |
 |---|---|---|
 | 2025-07-10 | v1.0 | Initial version |
 | 2025-07-10 | v1.1 | Post-review revision based on dual review merge (12 instructions): §Two-Day MVP Discipline rewritten as "MVP Discipline (Optimized for Speed)" -- no longer a cutting list, explicitly prohibits deferring P0 features without user confirmation; §Project Constraints gains three architecture constraints (httpx sync-only in background threads, pre-generated reports, single-task executor with 400 rejection); §Source Of Truth gains review-file inclusion, absolute-stop conflict resolution policy, anti-hallucination directive, and RequirementsDoc.md existence guard; §Development Workflow TDD instruction upgraded from "when practical" to mandatory-by-category with explicit TDD.md §2.1 citation; Error Handling Philosophy subsection added; §Testing And Verification gains coverage command and 80% target; §Git Workflow gains branch strategy with mandatory multi-agent branch isolation; §Multi-Agent Rules gains 4 construction-type parallel task examples; §Superpowers Workflow gains environment compatibility note and pre-verification cleanup rule; §Safety Rules gains raw_data sanitization guidance for fixtures; §Completion Standard gains Tasks.md checkbox sync requirement and explicit test-result reporting requirement. |