Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,10 @@ project.private.config.json
.claude/
.gstack/
.understand-anything/
mcp-gateway/
skills-lock.json
style-comparison.html

# Runtime logs
log/
*.log

# Local manual-test evidence artifacts
harness/manual-test-results.local*.json
harness/manual-test-summary.local*.md
harness/manual-artifact-manifest.local*.json
harness/manual-evidence-artifacts/
harness/devtools-recovery-report.local*.md
61 changes: 30 additions & 31 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,43 +8,41 @@ Street Tasks is a native WeChat mini program for short-lived neighborhood tasks.

The app can run locally from mock data and `wx` local storage, and it also has CloudBase-backed paths for shared posts, reactions, comments, feedback, viral attribution events, images, and admin role checks. Treat `utils/store.js` as the main persistence boundary; page code should not duplicate storage or cloud fallback logic.

## Harness Operating Loop
## Project Knowledge Base

This repository keeps agent state, verification, and handoff files under `harness/`. Treat those files as the durable source of truth for long-running AI-assisted work.
This repository keeps durable product, architecture, data, safety, privacy, and
launch knowledge under `knowledge/`. Treat it as the source of truth for how the
product is supposed to behave; code and platform state take priority when they
disagree, and the docs should then be corrected.

Before changing code:

1. Run `pwd` and confirm the repo root is `/Users/bytedance/git/x`.
2. Read `harness/claude-progress.md` for the latest verified state, blocker, and next action.
3. Read `harness/feature_list.json` and pick the highest-priority unfinished feature. Keep at most one feature `in_progress`.
4. Check recent history with `git log --oneline -5`.
5. Run `bash harness/init.sh`. If it fails, fix the base state before adding feature work.
2. Read `knowledge/index.md` and the relevant topic article for the area you are
touching (e.g. `knowledge/data-model.md`, `knowledge/trust-safety.md`).
3. Check recent history with `git log --oneline -5`.
4. Run `npm run check`. If it fails, fix the base state before adding new work.

Required harness files:
Key knowledge articles:

- `harness/feature_list.json`: machine-readable feature status and verification evidence.
- `harness/claude-progress.md`: session log and current verified state.
- `harness/init.sh`: single bootstrap and baseline verification entrypoint.
- `harness/session-handoff.md`: short handoff summary for longer sessions.
- `harness/clean-state-checklist.md`: closeout checklist before handing work back.
- `harness/evaluator-rubric.md`: acceptance rubric for completed work.
- `harness/quality-document.md`: project quality snapshot by product area and architecture layer.
- `knowledge/index.md`: entry point linking every topic article.
- `knowledge/product-overview.md`: product scope, categories, and non-goals.
- `knowledge/architecture.md`: page layer, shared modules, and cloud boundary.
- `knowledge/data-model.md`: entities, fields, and status-transition rules.
- `knowledge/trust-safety.md` / `knowledge/privacy-security.md`: moderation,
content safety, consent, and public-data limits.
- `knowledge/development-verification.md` / `knowledge/release-readiness.md`:
how to verify changes and what still blocks launch.

Follow `knowledge/AGENTS.md` when maintaining the knowledge base itself; record
structural changes in `knowledge/log.md`.

Completion definition:

- The target behavior is implemented.
- Required verification actually ran.
- Evidence is recorded in `harness/feature_list.json` or `harness/claude-progress.md`.
- The repo can still be restarted from `bash harness/init.sh`.
- Required verification actually ran (`npm run check` plus targeted `node --check`).
- Any skipped manual WeChat DevTools checks are called out as unverified, not implied passing.

Session closeout:

1. Update `harness/claude-progress.md`.
2. Update `harness/feature_list.json` when feature status or evidence changes.
3. Note unresolved risks or blockers.
4. Run the relevant verification commands.
5. Leave the next session able to continue from repo files alone.
- Knowledge articles are updated if the change alters documented product behavior.

## Tech Stack

Expand All @@ -70,7 +68,7 @@ Session closeout:
- `utils/post-presenter.js`: shared presentation helpers for profile/activity pages.
- `utils/diagnostics.js`: runtime diagnostics used by map startup and fallback paths.
- `utils/mock-posts.js`: seed data used when local storage is empty.
- `harness/*`: agent harness state, verification, closeout, and quality tracking files.
- `knowledge/*`: durable product, architecture, data, safety, privacy, and launch knowledge base.
- `DESIGN_SYSTEM.md`: current visual design rules and native/TDesign-style component patterns.
- `PROJECT_SUMMARY.md`: high-level project summary for humans and future agents.
- `pages/map/*`: map feed, marker interactions, and list overlay.
Expand Down Expand Up @@ -108,20 +106,21 @@ There is no general unit test suite yet.
Use these baseline checks for most changes:

```bash
bash harness/init.sh
node scripts/check-json.mjs
node harness/check-harness.mjs
npm run check
git diff --check
```

`npm run check` runs the JSON syntax check, the knowledge-base structure check,
and the product-behavior readiness checks under `scripts/`.

After editing JavaScript, run targeted syntax checks, for example:

```bash
node --check pages/map/map.js
node --check utils/store.js
```

User-visible mini program behavior still needs WeChat DevTools or real-device verification. Record any manual evidence, skipped checks, or remaining risks in `harness/claude-progress.md` or `harness/feature_list.json`.
User-visible mini program behavior still needs WeChat DevTools or real-device verification. Record any manual evidence, skipped checks, or remaining risks alongside the related change (commit, PR, or issue), and update the relevant `knowledge/` article if documented behavior changes.

## Data Model Notes

Expand Down Expand Up @@ -164,7 +163,7 @@ CloudBase is optional for local development but required for shared multi-user d
- `viral_attribution_events`
- `admins`

Text-only posts may fall back to local storage when cloud APIs are unavailable. Image posts are stricter: selected images are compressed, capped at 4 files under 1.5MB each, uploaded to CloudBase Storage, and saved as `cloud://` file IDs. If cloud upload or cloud post creation fails for an image post, fail explicitly instead of saving local-only temp image paths.
Local storage is used only when CloudBase is disabled for development. Once CloudBase is enabled, publish and comment failures must be surfaced instead of silently falling back to local success. Image posts are stricter: selected images are compressed, capped at 4 JPG/JPEG/PNG files under 1MB each and no larger than 750×1334, and images with unknown types or dimensions are rejected. Accepted images are uploaded to CloudBase Storage and saved as `cloud://` file IDs. If cloud upload, safety checking, or cloud post creation fails for an image post, fail explicitly instead of saving local-only temp image paths.

## Coding Conventions

Expand Down
Loading
Loading