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:

```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.

### 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:

```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. |