87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
 
|
# AGENTS.md
|
||
|
|
|
||
|
|
> Repository-level rules for AI coding agents. Read this before changing files.
|
||
|
|
|
||
|
|
## Mission
|
||
|
|
|
||
|
|
Build a mobile-first, installable, offline-capable English intensive-listening PWA for "Family Album, U.S.A." using audio plus sentence-synced English subtitles. The MVP is not a video site, social product, generic course platform, or AI speaking scorer.
|
||
|
|
|
||
|
|
## Required Reading Order
|
||
|
|
|
||
|
|
Before writing code, read these files in order:
|
||
|
|
|
||
|
|
1. `docs/00-ai-start-here.md`
|
||
|
|
2. `docs/01-vision.md`
|
||
|
|
3. `docs/02-requirements.md`
|
||
|
|
4. `docs/03-tech-stack.md`
|
||
|
|
5. `docs/04-architecture.md`
|
||
|
|
6. `docs/05-coding-rules.md`
|
||
|
|
7. `docs/06-tasks.md`
|
||
|
|
8. `CLAUDE.md`
|
||
|
|
|
||
|
|
Use `docs/00-ai-start-here.md` for navigation. Use `docs/05-coding-rules.md` as the hard implementation rulebook.
|
||
|
|
|
||
|
|
## Task Discipline
|
||
|
|
|
||
|
|
- Work from `docs/06-tasks.md`.
|
||
|
|
- Pick only the first `TODO` task whose dependencies are all `DONE`.
|
||
|
|
- Do exactly one task per development turn.
|
||
|
|
- Mark it `DOING` before implementation, then `DONE` only after its acceptance checks pass.
|
||
|
|
- Do not jump ahead, batch multiple tasks, or add V2/V3 scope while doing MVP work.
|
||
|
|
|
||
|
|
## MVP Scope
|
||
|
|
|
||
|
|
MVP scope is ep1-17 plus these P0 capabilities:
|
||
|
|
|
||
|
|
- Course list
|
||
|
|
- Audio playback
|
||
|
|
- Sentence-synced subtitles
|
||
|
|
- Vocabulary notebook
|
||
|
|
- Account and cross-device sync
|
||
|
|
- PWA install/offline use
|
||
|
|
|
||
|
|
Do not implement video playback, line-level Chinese translation, social features, AI speaking scoring, SRS, tests/quizzes, AB repeat, or multi-course logic unless a task explicitly asks for it.
|
||
|
|
|
||
|
|
## Technical Constraints
|
||
|
|
|
||
|
|
- Frontend: go-app, Go to WebAssembly.
|
||
|
|
- Styling: plain CSS files, mobile-first, loaded via go-app handler styles.
|
||
|
|
- State: go-app native state and observers.
|
||
|
|
- Backend: Go `net/http`.
|
||
|
|
- Database: SQLite for user data only.
|
||
|
|
- Auth: httpOnly Session Cookie.
|
||
|
|
- Deployment target: single self-hosted Go binary serving wasm, static assets, audio, and APIs.
|
||
|
|
- Do not add new frameworks, heavy libraries, or third-party dependencies without explicit approval.
|
||
|
|
|
||
|
|
## Data Rules
|
||
|
|
|
||
|
|
- Content truth source: `family-album-usa/episodes.json`.
|
||
|
|
- Do not invent fields. `line` has only `{ "t", "en" }`; there is no `zh`.
|
||
|
|
- JSON audio paths such as `/family-album/audio/u0101.mp3` are service paths. Map them to disk under `family-album-usa/audio/`.
|
||
|
|
- Do not fabricate audio for ep18-26.
|
||
|
|
- `notion_docs/` and `*.bak` are read-only archives. Do not edit, delete, or treat them as source of truth.
|
||
|
|
|
||
|
|
## Verification
|
||
|
|
|
||
|
|
Before claiming a task is done, run the relevant checks from `docs/05-coding-rules.md` and report exactly what passed or failed.
|
||
|
|
|
||
|
|
This project is primarily developed under WSL / Linux (bash). Use bash commands first:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
GOOS=js GOARCH=wasm go build -o app.wasm # frontend wasm
|
||
|
|
go build # backend
|
||
|
|
go vet ./...
|
||
|
|
python3 scripts/validate_episodes.py
|
||
|
|
```
|
||
|
|
|
||
|
|
Windows PowerShell equivalents:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
|
||
|
|
go build
|
||
|
|
go vet ./...
|
||
|
|
python scripts/validate_episodes.py
|
||
|
|
```
|
||
|
|
|
||
|
|
Only run the content validator when content data or its schema is touched.
|