ilaandClaude Opus 4.8
b9bcbf7e6b
新增（Codex 起草，本次纳入并校对）： - AGENTS.md：仓库级 AI 强约束入口 - docs/00-ai-start-here.md：AI 开发入口与导航 - docs/api.md：账号/生词本/进度 API 合约草案 - docs/routes.md：go-app 页面路由与组件归属 - docs/current-state.md：当前实现状态 补充与对齐： - 验证命令补 bash（WSL/Linux 为主，PowerShell 为备）：00-ai-start-here、AGENTS - 04-architecture：新增第六节"项目结构（包布局）"+ 3.2 建表 SQL 草案 - docs/README 导航补 06-tasks；CLAUDE 目录树补 AGENTS/scripts/design_mockups - 00-ai-start-here 去除已过时的"需要补齐"段 - 06-tasks：Phase 2/3/4/5 交叉引用 api.md / routes.md / 包布局 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
|