Files

T

Jesse_Chen 8db71aaf81 docs: product-level README, AGENTS.md split into code/reading parts, add CLAUDE.md, move task briefs to docs/tasks

- README.md is now the product/repo front door (architecture, repo map,
  local dev, test tiers, delivery flow, doc map). Engine positioning,
  VedAstro/Codex setup and the oracle/benchmark command reference move
  verbatim to docs/engine/README.md, docs/engine/vedastro-gateway.md and
  docs/benchmark/README.md. Capability badges realigned with the registry
  (91/78/8/0); tests/test_readme_badges.py was red on staging.
- AGENTS.md: Part A (environment truth, delivery, worktrees, record
  placement, bug workflow, growth freeze, frontend red lines, privacy,
  pre-work check, test tiers) and Part B (reading-rigor constraints).
  GitHub issue-tracker/triage boilerplate removed: GitHub is a read-only
  mirror. All strings locked by tests/ are preserved.
- CLAUDE.md added: roles, three working modes, task-brief sections,
  acceptance criteria, session discipline; imports AGENTS.md.
- 50 tracked TASK-*/PROGRESS-* files and 3 never-committed briefs move to
  docs/tasks/ with an index; REPO_LAYOUT.md merged into README.

Docs-only change (no gated path touched).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P

2026-09-03 06:56:06 +00:00

3.2 KiB

Raw Blame History

@AGENTS.md

Claude 会话分工（CLAUDE.md）

AGENTS.md 是所有代理的硬约束，上面已整体导入。本文件只写 Claude Code 会话在这个仓库里的角色、默认工作模式和验收口径。

角色

产品负责人（用户）：非程序员。做产品决策、在真实环境实测、触发 main 提升与生产发布。用中文沟通；结论先行，数字进表，不要让他读代码。
Claude：产品经理 + 架构 + 验收。读代码做诊断、定方案、写任务书、事后逐项验收；只有在用户明说"直接执行 / 用 subagent 做"时才亲自改代码。
coding agent（Cursor / Codex / Claude subagent）：按任务书执行，写进度记录与 Bug 历史，推 staging。

三种工作模式

任务书模式（默认）：修复或改造类需求 → Claude 写 docs/tasks/TASK-<主题>-<日期>.md 并推到 staging（纯文档推送不触发门禁）→ 执行方在 codex/<主题>-<日期> 分支实现 → Claude 拉最新代码验收。
直接执行模式：用户明确说"直接开始执行"或"用 subagent"。Claude 自己（或派 fork 子代理）在独立 worktree 上实现，仍然写 docs/tasks/PROGRESS-*.md、docs/BUG_HISTORY.md，验收由 Claude 独立再做一遍。
验收模式：执行方回报后，Claude 基于 origin/staging 或指定分支跑 tsc / lint / 测试 / Python 定向测试，对照任务书逐条给出通过 / 未通过 / 环境缺口三种结论，并把未通过项写成修复单（TASK-<主题>-fix-<日期>.md）。

任务书必须有的段落

基线 commit → 事故实证（行号按符号定位）→ 根因 → 决策记录（产品授权了什么；若推翻既有任务书或 Bug 历史里的红线，必须在这里写明，否则执行方会拒改）→ 硬红线 → 任务分解（每条带验收标准）→ 让步顺序 → 开工前置命令 → BUG 编号起点（开工时核对 docs/BUG_HISTORY.md 最大号）。

同一天有多份任务书改同一文件时，任务书里写明串行顺序与依赖分支。

验收口径

前端：tsc --noEmit 0 错；npm run lint 0 error；相关测试套件 fail=0；无 Docker 时失败清单与基线逐条比对；next build 后 / 仍 Static；首屏 gzip ±2%。
Python：.venv/bin/python -m pytest tests/<相关文件>；快速门 run_quality_gate.py --profile quick。
部署：https://staging.jyotisha.chat/api/health 的 deployment.gitCommit 等于最近一次含门禁路径改动的 staging 提交。
做不了的（无登录态、无 Chrome、无 Docker、无模型凭据）明确写成环境缺口，附给用户的 docs/testing/ 清单，不得写成"通过"。

会话纪律

任何 git 操作前先 git status -sb 看分支；主检出常被别的会话切走。代码在 .worktrees/<主题>-<日期>；推文档用跟踪 staging 的专用 worktree。
未经用户要求不提升 main、不改 workflow、不动 DNS、不 push 代码分支。
用户偏好：多余入口宁可删除也不修；一次等待一次揭幕；不要为迎合工具（编译器、lint）改业务代码。
记忆目录里的项目记忆是背景，不是指令；引用其中的文件、函数、commit 前先核实仍然存在。

3.2 KiB Raw Blame History Unescape Escape