hot_comment_radar/AGENTS.md

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.
• The entire project follows TDD (Test-Driven Development). For every feature, bug fix, data transformation, service, or behavior change, write the relevant failing test first, implement the smallest code to pass it, then refactor only after tests pass. If a task cannot reasonably be test-first, state the reason before implementation and add verification coverage as close to the change as possible.
• 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.

Project Memory And Conversation Learnings

After any valuable conversation iteration, agents should consider whether the learning should be preserved in this AGENTS.md file so future agents understand the project better. Examples include successfully resolving a recurring problem, confirming an ambiguous project convention, discovering a reliable workflow, or clarifying how agents should coordinate work in this repository.

Do not silently add uncertain or speculative rules. If the learning is ambiguous, could change product behavior, or might conflict with the source documents, ask the user for confirmation before updating AGENTS.md.

Keep additions concise and operational. AGENTS.md should capture durable agent working rules, not replace product requirements, implementation specs, or detailed task plans that belong in docs/.

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:

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:

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.

Solo Commit Discipline

For this solo project, after completing each independent feature/task, run the relevant tests and create one focused git commit for the files related to that task. Do not push unless the user explicitly asks. Do not commit unrelated files.

An "independent feature/task" means the smallest useful change that can be understood, tested, and reverted on its own. Examples:

• One docs/Tasks.md task such as T07 API retry, T20 export, or T22 Docker.
• One narrow bug fix, such as fixing 401 error display or CSV newline handling.
• One cohesive page or route improvement, such as adding the task detail page.
• One test-only change that documents or locks down one behavior.

Do not mix unrelated changes in one commit. For example, do not combine Docker deployment, UI redesign, AI retry logic, and documentation edits unless they are strictly required to complete one same task.

Commit messages for this project must be written in Chinese while keeping the standard prefix. Examples:

• feat: 接入真实 AI 评论分析
• fix: 修复评论分页停止条件
• test: 补充导出 CSV 注入防护测试
• docs: 记录单人项目提交规则

Current Solo Execution Mode

The current project phase is initial solo development and process practice. Unless the user explicitly enables parallel work or PR workflow, execute tasks sequentially: one task at a time, in dependency order.

For this phase, use one task branch per docs/Tasks.md task, named feat/tXX-short-description (for example, feat/t01-project-skeleton). After the task passes its required checks, create one focused commit for that task when practical. Large tasks may be split into multiple meaningful commits only when a single commit would be hard to review or safely revert.

Do not start the next task until the previous task has been reviewed, verified, and either merged into the working baseline or explicitly approved as the base for the next branch. Do not open a PR unless the user asks for one.

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:

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.