opc/lingo

Files

T

ilaandClaude Opus 4.8 b9bcbf7e6b 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>

2026-06-21 19:30:14 +08:00

3.0 KiB

Raw Blame History

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:

docs/00-ai-start-here.md
docs/01-vision.md
docs/02-requirements.md
docs/03-tech-stack.md
docs/04-architecture.md
docs/05-coding-rules.md
docs/06-tasks.md
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:

GOOS=js GOARCH=wasm go build -o app.wasm   # frontend wasm
go build                                    # backend
go vet ./...
python3 scripts/validate_episodes.py

Windows PowerShell equivalents:

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

3.0 KiB Raw Blame History