From 6c9acbc50131982b64f9d974c1464842868d5f69 Mon Sep 17 00:00:00 2001 From: tupingr Date: Mon, 25 May 2026 17:23:06 +0800 Subject: [PATCH] =?UTF-8?q?chore(arch):=20=E8=AE=B0=E5=BD=95=E4=BB=8A?= =?UTF-8?q?=E6=97=A5=E5=B7=A5=E4=BD=9C=20+=20=E6=9B=B4=E6=96=B0=E6=98=8E?= =?UTF-8?q?=E6=97=A5=E4=BB=BB=E5=8A=A1=20+=20=E5=90=8C=E6=AD=A5=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - journal: 2026-05-25 完整工作记录 - arch/today.md: 标记完成，列出明日待办 - ROADMAP.md: 进度更新至40%，信息架构重构标为完成 - 从 ai_project 同步 ADR-008 + P-003 到 main Co-Authored-By: Claude Opus 4.7 --- .ai/knowledge/decisions.md | 15 ++++++ .ai/knowledge/journal/2026-05-25.md | 83 ++++++++++++++++++++--------- .ai/knowledge/patterns.md | 16 ++++++ .ai/roles/arch/today.md | 27 +++++----- ROADMAP.md | 16 +++--- 5 files changed, 109 insertions(+), 48 deletions(-) diff --git a/.ai/knowledge/decisions.md b/.ai/knowledge/decisions.md index c61599e..4e04050 100644 --- a/.ai/knowledge/decisions.md +++ b/.ai/knowledge/decisions.md @@ -55,3 +55,18 @@ - 决策: 采用四层信息架构（工作台 → 路线图 → 阶段上下文 → 知识沉淀），每层有 token 预算 - 理由: AI 上下文窗口有限（~200K tokens），旧 AGENTS.md 单体文件浪费 token；每个 AI 角色只需要知道自己该干什么 - 影响: 所有 AI 从 `.ai/roles/{role}/` 启动；新增 `ROADMAP.md`、`DASHBOARD.md`、`docs/share/` 分享层 + +## ADR-008: 框架/项目双分支 + 同步机制 + +- 日期: 2026-05-25 +- 状态: 已采纳 +- 决策: 采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支 +- 理由: + - 框架层变化需要传播到模板，但重做去敏化消耗巨大（~100K tokens） + - 两个分支的差异本质是"变量替换"，可以脚本自动化 + - 框架层（AGENTS/权限/提示词/工作流）和项目层（任务/日志/代码）的边界清晰 +- 影响: + - 新增 `SYNC.md` 定义框架层/项目层边界 + - 新增 `sync-template.sh` 实现自动同步 + - 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化 + - AI 项目框架从此可复用，token 节省 95%+ diff --git a/.ai/knowledge/journal/2026-05-25.md b/.ai/knowledge/journal/2026-05-25.md index 490ebba..b4b18a1 100644 --- a/.ai/knowledge/journal/2026-05-25.md +++ b/.ai/knowledge/journal/2026-05-25.md @@ -1,35 +1,70 @@ -# 2026-05-25 — 信息架构重构 +# 2026-05-25 — 信息架构重构 + 模板化 ## 做了什么 -完成项目信息架构从"人类导向单体文档"到"AI 优先分层架构"的全面重构。 +### 1. 信息架构重构（Arch AI 角色） +将项目从"人类导向单体文档"重构为"AI 优先分层架构"： -### 新增 (~35 个文件) +**新增四层信息架构：** +- Layer 0: 角色工作台 `.ai/roles/{arch,dev,qa}/` — 每个 AI 每天只读 card.md + today.md（< 2K tokens） +- Layer 1: 路线图看板 `ROADMAP.md` — 人+AI 共享进度 +- Layer 2: 阶段上下文 `.ai/phases/phase-NN/` — 按需加载（< 5K tokens） +- Layer 3: 知识沉淀 `.ai/knowledge/` — 自动积累决策/模式/教训 -- **角色工作台** (`.ai/roles/`): 为 Arch/Dev/QA 三个 AI 角色各创建 card.md + today.md + queue.md，AI 每天只需读 2 个小文件即可开工 -- **阶段上下文** (`.ai/phases/`): Phase 1-4 的阶段目标、范围、架构决策文档。当前 Phase 1 已填充，Phase 2-4 为模板占位 -- **知识沉淀** (`.ai/knowledge/`): decisions.md（迁移 6 个旧 ADR + 新增 ADR-007）、patterns.md、lessons.md -- **架构提示词** (`.ai/prompts/architecture/`): 补充之前缺失的架构设计和技术选型模板 -- **分享层** (`.ai/share/`): 阶段复盘模板、决策故事模板、项目缘起和框架设计思路占位 -- **人类仪表盘** (DASHBOARD.md): 根目录，30 秒可读 -- **路线图看板** (ROADMAP.md): 阶段进度 + 任务看板 + 阻塞项，人机共享 -- **任务索引** (review/active/INDEX.md): 所有活跃任务一览 +**新增关键文件：** +- `DASHBOARD.md` — 人类仪表盘（根目录，30 秒可读） +- `ROADMAP.md` — 阶段进度 + 任务看板 + 阻塞项 +- `docs/使用手册.md` — 人+AI 完整使用手册 +- `.ai/principles.md` — 信息架构设计原则 +- `.ai/prompts/architecture/` — 补充缺失的架构提示词模板 -### 修改 (6 个文件) +**压缩改写：** +- AGENTS.md: 239行 → 117行 +- README.md: 167行 → 88行 +- PROJECT_CONTEXT.md: 117行 → 52行 -- AGENTS.md: 239 行 → ~120 行，顶部 AI 跳转 -- README.md: 精简，聚焦人类读者 -- docs/PROJECT_CONTEXT.md: 精简，加跳转链接 -- docs/DECISIONS.md: 替换为跳转存根 -- 5 个 task.md: 添加 phase 字段 +**一鸡多吃分享层：** +- `docs/share/` — 阶段复盘模板、决策故事模板 -## 关键决策 +### 2. 项目模板化（ai_project 分支） +将 ErrLens 框架去敏化为通用 AI 协作项目模板： -1. 分层信息架构：工作台 → 路线图 → 阶段上下文 → 知识沉淀 -2. Token 预算制度：每个文件标注预算上限 -3. "一鸡多吃"：开发过程自动沉淀为可分享内容 -4. 角色工作台代替全局 AGENTS.md 作为 AI 入口 +- 创建 `TEMPLATE.yaml` — 14 个模板变量定义 +- 创建 `init.sh` — 一键初始化新项目的脚本 +- 创建 `sync-template.sh` — 从 main 同步框架层到模板分支 +- 创建 `SYNC.md` — 框架层/项目层边界定义 +- 98 处 {{变量}} 覆盖所有关键位置 +- 双分支策略：main（具体项目） + ai_project（通用模板） -## 经验教训 +### 3. 知识沉淀 +- ADR-007: 分层信息架构 + Token 预算 +- ADR-008: 框架/项目双分支 + 同步机制 +- P-001: AI 任务交接模式 +- P-002: 角色工作台模式 +- P-003: 模板同步模式 +- L-001: 单体 AGENTS.md 浪费 AI 上下文 -见 lessons.md L-001: 单体 AGENTS.md 浪费 AI 上下文 +## 当前状态 + +- 分支: main（ErrLens 开发） +- 阶段: Phase 1 基础搭建，进度 ~40% +- 信息架构重构: ✅ 完成 +- 模板化: ✅ 完成（在 ai_project 分支） +- 所有代码已推送远程 + +## 下一步（明天继续） + +Arch AI 下一步: +1. 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 +2. 设计 `docs/02_系统架构/` — 系统架构文档 +3. 将 P01 项目文档从"代码检测"改写为"错题本" + +## Git 提交记录 +- 4184a6d: 信息架构重构（main） +- 0df22a2: 去敏化为模板（ai_project） +- 05b87a9: 模板同步机制（ai_project） +- 46af1f8: ADR-008 + P-003（ai_project） + +## 注意 +- ai_project 分支上还有 ADR-008 和 P-003，main 上尚未同步（本次会补上） +- 如果明天接不上，读 DASHBOARD.md + .ai/roles/arch/card.md + .ai/roles/arch/today.md 即可 diff --git a/.ai/knowledge/patterns.md b/.ai/knowledge/patterns.md index 668f4e4..351628b 100644 --- a/.ai/knowledge/patterns.md +++ b/.ai/knowledge/patterns.md @@ -32,6 +32,22 @@ --- +--- + +## P-003: 模板同步 (framework sync) + +**上下文**: 项目框架层（AGENTS/权限/提示词/工作流）的变化需要传播到通用模板分支 +**问题**: 手动同步耗时且容易遗漏，AI 重做去敏化消耗 ~100K tokens +**方案**: +- 双分支：`main`（具体项目）+ `ai_project`（通用模板） +- `SYNC.md` 明确定义框架层/项目层文件边界 +- `sync-template.sh` 自动 checkout 框架文件 + 重新应用 {{变量}} +- 框架层 ~15 个文件自动同步，project 层永久隔离 +**何时用**: main 分支框架有变化时 +**维护者**: Arch AI 触发，脚本执行 + +--- + ## 反模式（避免） - 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录 diff --git a/.ai/roles/arch/today.md b/.ai/roles/arch/today.md index b87eea0..c1b8bff 100644 --- a/.ai/roles/arch/today.md +++ b/.ai/roles/arch/today.md @@ -1,22 +1,19 @@ # Arch AI · 今日任务 · 2026-05-25 -## 进行中 - -- [ ] 信息架构重构 — 正在实施 - -## 待办（按优先级） - -1. **[P0]** 完成信息架构重构（所有文件创建 + 改写） -2. **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 -3. **[P0]** 将 P01 项目文档从"代码检测"重写为"错题本" -4. **[P1]** 设计 `docs/02_系统架构/` — 系统架构文档 -5. **[P1]** 补充 `.ai/prompts/architecture/` 提示词模板 - ## 已完成 -- [x] 分析项目现状，识别架构问题 -- [x] 输出信息架构重构方案 +- [x] 信息架构重构 — 四层分层架构全部落地 +- [x] DASHBOARD.md + ROADMAP.md + docs/使用手册.md +- [x] 项目模板化（ai_project 分支）+ 同步机制 +- [x] 知识沉淀：ADR-007, ADR-008, P-001~003, L-001 + +## 明天 (2026-05-26) + +1. **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 +2. **[P0]** 设计 `docs/02_系统架构/` — 系统架构文档 +3. **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本" +4. **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务） ## 阻塞 -（无外部阻塞） +（无） diff --git a/ROADMAP.md b/ROADMAP.md index a7d92ed..ed92194 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,7 +7,7 @@ ## 阶段总览 ``` -Phase 1 [====------] 基础搭建 ← 当前 (30%) +Phase 1 [=====-----] 基础搭建 ← 当前 (40%) Phase 2 [----------] MVP (0%) Phase 3 [----------] 功能完善 (0%) Phase 4 [----------] 打磨发布 (0%) @@ -15,7 +15,7 @@ Phase 4 [----------] 打磨发布 (0%) | 阶段 | 名称 | 状态 | 进度 | 预计重点 | |------|------|------|------|----------| -| 1 | 基础搭建 | ACTIVE | ~30% | 框架、脚手架、权限、信息架构 | +| 1 | 基础搭建 | ACTIVE | ~40% | 框架、脚手架、权限、信息架构 | | 2 | MVP | PLANNED | 0% | 错题录入、AI 分析、基础展示 | | 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端适配、训练迭代 | | 4 | 打磨发布 | PLANNED | 0% | 性能优化、安全审计、文档完善 | @@ -38,15 +38,13 @@ Phase 4 [----------] 打磨发布 (0%) | 任务 | 项目 | 描述 | 负责人 | 预计完成 | |------|------|------|--------|----------| -| — | 全局 | 信息架构重构 | Arch AI | 2026-05-25 | - -### REVIEW（待验收） - -（空） +| — | 全局 | 编写错题本 PRD | Arch AI | 2026-05-26 | ### DONE（已完成） -（空） +| 任务 | 项目 | 描述 | 完成日期 | +|------|------|------|----------| +| — | 全局 | 信息架构重构 | 2026-05-25 | --- @@ -64,5 +62,5 @@ Phase 4 [----------] 打磨发布 (0%) | 日期 | 事件 | |------|------| -| 2026-05-25 | 信息架构重构：分层 AI 上下文 + 角色工作台 + 分享层 | +| 2026-05-25 | 信息架构重构完成 + 项目模板化（ai_project 分支） | | 2026-05-23 | 框架搭建完成：目录结构、权限体系、7 个 Skill |