bai/curriculum-project-hub
1
0
Fork 1
forked from EduCraft/curriculum-project-hub
Code Pull Requests Activity
Files
3f9b60f692e1d4e2e9ae4d38bc6af022a7e8d457
curriculum-project-hub/AGENTS.md
T
hongjr03 3f9b60f692 chore: remove Lean spec; ADRs are the single source of truth 
The spec/ Lean semantic master had no conformance gate, no codegen, and
no CI tie to implementations — alignment was carried entirely by human
review, the same mechanism that carries the ADRs. In practice the ADRs
plus greppable code comments were already the load-bearing artifacts,
so spec/ was the most expensive kind of stale documentation.

- delete spec/ and the spec-check CI workflow
- README: constitution rewritten around ADRs as decision truth
- AGENTS.md/CLAUDE.md: discipline re-anchored (new decisions -> new ADR,
  never rewrite ADR history; supersede instead)
- code comments: re-anchor 'Mirrors Spec.X' invariants to ADR numbers
  (cph-diag, cph-check, cph-model, hub runner/capacity/org, prisma)
- leave ADR bodies and .scratch audit snapshots untouched (history);
  fix live references in open readiness tickets
2026-07-20 09:07:26 +00:00

4.3 KiB
Raw Blame History

AGENTS.md —— agent 操作手册(全 repo)

本 repo 是 monorepo。先读根 README.md 的"宪法"4 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。

这个 repo 是什么

  • docs/adr/ 是系统级决策的唯一权威来源;CONTEXT.md 是平台语言词汇表;代码注释把关键不变量锚到 ADR 编号,可 grep。
  • hub/ 的平台层按 SaaS 形态演进:Organization 是 tenant root;Project/Team 必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020)。
  • org 后台 project explorer 里 Folder 是透明组织节点,不是权限资源;project 仍是权限边界。 普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021)。
  • 每个 org 自选 BYOK 或平台托管 model provider connection;平台托管也必须是该 org 独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021)。
  • Feishu/provider secret 使用本地版本化 master-key keyring 的信封加密;生产由 systemd credential 注入,运行时只允许显式 org/project scope 的 fail-closed resolver,不得回退 process-global credential;Agent child 只接收 run-scoped loopback proxy capability, 不接收 org provider credential(见 ADR-0024)。
  • 生产容量按不可突破的 platform ceiling 与 org 可下调 policy 分层;有效限制取两者较低值。 Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022)。
  • 平台管理员只通过独立的 platform-owned 飞书应用与可撤销 Platform Session 认证,不复用 客户 User/org membership;平台写操作与 append-only audit 同事务,break-glass 只走 双因子的离线恢复流程(见 ADR-0023)。
  • 受控 alpha 暂采用一 Organization 一具名 systemd Silo:独立 database role/database、 service identity、workspace、keyring 与 Feishu/provider connection；进程必须由 HUB_SILO_ORGANIZATION_ID fail-closed 绑定唯一 org，平台后台不开放。共享 SaaS 控制面与 Docker adapter 后置(见 ADR-0025)。
  • Agent role 与 skill 是 Organization-scoped 动态运行配置：role 组合 model、system prompt、 tools 与已安装 skill；skill 版本进入 content-addressed 持久存储，run 只读加载所选快照。 每个 Organization 必须且只能有一个启用中的默认 role；新建群绑定从该默认值初始化，之后 ProjectGroupBinding 持久化群内当前 role，run 在接纳时冻结该 role。飞书公开 slash 协议只含 /project、/usage、/help；role、会话、目录操作走 /project 卡片，Claude 原生 /compact 只能由卡片动作以未经包装的精确 prompt 转发。 settingSources: [] 继续禁用项目/用户配置加载，不得把任意 workspace .claude 配置变成 运行时能力(见 ADR-0018)。
  • 项目发现由 ProjectDiscovery 模块统一承载：PostgreSQL pg_trgm 搜索派生文档、项目编号 归一化、完整 Folder breadcrumb、MANAGE 授权过滤与分页都在该模块内；飞书卡片只是 adapter。 Project/Folder 仍是事实来源，搜索文档必须可重建且由数据库触发器同步，禁止调用方双写。 系统 Inbox 只作为未分类项目的内部落点，不作为业务 folder 暴露；已绑定群通过 @bot /project 随时打开项目管理卡片，重命名仍走 org-scoped MANAGE 授权与审计。

纪律

  1. 不得用预训练先验脑补本领域。 这个领域很新,你没有相关先验。ADR 与 CONTEXT.md 是语义的唯一权威来源;没写的,就是没定的。

  2. 凡 ADR 未写明者,不得假设。 遇到没覆盖的地方,显式 surface 出来让开发者决定,绝不擅自替它选一个解。

  3. 新语义决策进 ADR。 跨部件的语义分歧点按编号顺延新增 docs/adr/NNNN-*.md;代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。已有 ADR 正文不改写历史——推翻旧决策就写新 ADR 标记 supersede。

  4. 实现向 ADR 对齐;偏离必须 surface。 没有 CI gate 替你把关 ADR↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与决策不一致时,报告它,不要默默让其中一边将就另一边。

  5. 写操作谨慎。 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。

View Git Blame Copy Permalink