docs: 补全 AI 入口/API/路由/现状文档并对齐一致性
新增(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>
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user