diff --git a/README.en.md b/README.en.md index 714b18c..c1be4b1 100644 --- a/README.en.md +++ b/README.en.md @@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow

Status - CodeStable Skills + CodeStable Skills License

@@ -95,13 +95,13 @@ CodeStable models real coding work as a set of **entities** and **flows**. | Entity | Slug | What it does | |------|------|--------| -| **Requirement** | requirements | Original user stories, the discussion and trade-offs at the time. The escape hatch — when code rots, you can throw it all out and let AI regenerate from these | -| **Architecture** | architecture | What the system's orchestration layer looks like to deliver the requirements. Concise, unified, **for humans to read** — not for AI to talk to itself | +| **Requirement** | requirements | User stories + domain glossary (CONTEXT.md) + architecture decisions (ADRs). The escape hatch — when code rots, you can throw it all out and let AI regenerate from these | | **Roadmap** | roadmap | "I want a permission system" — too big to throw at AI as a feature; cut it into a roadmap and advance step by step | | **Goal** | goals | Bounded start/end: write a start report, then let AI iterate autonomously on implementation/validation, with subagent functional acceptance before completion | | **Feature** | feature | The actual engineering execution. Human and AI collaborate, jointly responsible for design / implementation / acceptance | | **Issue** | issue | The bug list after release. AI and human solve it together | -| **Compound** | compound | The compounding-engineering knowledge base — pitfalls, good practices, technical decisions | +| **Refactor** | refactor | Cleanup process when code rots (beta) | +| **Compound** | compound | The compounding-engineering knowledge base — pitfalls, tricks, investigation notes | ### Flows @@ -120,6 +120,32 @@ CodeStable models real coding work as a set of **entities** and **flows**. ## Skill catalog + + + + + + + + + + + + + + + + + + + + + + + + +
GroupSkillPurpose
Root entrycsUnified entry — introduces the system and routes open-ended intents to the right cs-* skill. Call it when you don't know which one fits
Onboardcs-onboardBring CodeStable into a new repo or one with scattered docs
Requirement & domaincs-reqCurate / accumulate capability vision docs
cs-domainMaintain requirements/CONTEXT.md glossary + requirements/adrs/ architecture decisions (3-criteria gate + Nygard 4 sections) + single/multi context topology
Roadmapcs-roadmapUp-front planning for a big chunk of work: high-level design + interface contracts + sub-feature breakdown
Discussion entrycs-brainstormTriage when ideas are still fuzzy: route to design / continue in a feature / hand off to roadmap
Goalcs-goalBounded start/end: write a start report, let AI iterate autonomously, with subagent functional acceptance before completion
Feature flowcs-featSub-flow entry for new features
cs-feat-designDraft {slug}-design.md as the single input for what follows
cs-feat-implCode in the order the design lays out
cs-code-reviewCross-cutting read-only code review gate before commit; produces {slug}-review.md
cs-feat-acceptVerify implementation against the design layer by layer; close the loop
cs-feat-ffUltra-light lane: no design, no phases, AI just does it
Issue flowcs-issueSub-flow entry for issue fixing
cs-issue-reportTurn the problem in your head into a reproducible, traceable report
cs-issue-analyzeFind root cause, assess fix risk, propose options
cs-issue-fixTargeted fix + verification + write fix-note
Refactor flowcs-refactor(beta) Main refactor flow
cs-refactor-ff(beta) Light refactor lane
Knowledge sinkcs-keepSink pitfalls / tricks / decisions / exploration into compound/ as plain markdown, searched via grep
Outward docscs-doc-tutorialOutward-facing dev / user guides (task-oriented: how to use X to do Y)
cs-doc-apiAPI reference reverse-engineered from source (entry-by-entry, parts lookup)
+ See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily use, call `/cs` when you are unsure; it routes your intent to the right skill. --- @@ -128,7 +154,98 @@ See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for the full catalog. In daily CodeStable's skills are **layered + event-driven**: root routing, onboard, long-lived archives, roadmap planning, feature / issue / refactor execution flows, and cross-cut knowledge sinking. -See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full diagram. +``` +═══════════════════════════════════════════════════════════════════════ + Root entry · routing (callable any time) +─────────────────────────────────────────────────────────────────────── + cs ──▶ Introduce the system / route open-ended intent to a sub-skill + (does nothing itself — only triages and points) +═══════════════════════════════════════════════════════════════════════ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + (not onboarded) (onboarded) (just want to learn) + go to phase 0 jump to L1~4 / cross-cut quick read + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + Phase 0 · Onboard (runs once per project) +─────────────────────────────────────────────────────────────────────── + cs-onboard ──▶ Generate codestable/ skeleton + release reference/, tools/ +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + Layer 1 · Long-lived archive ("what the system looks like now") +─────────────────────────────────────────────────────────────────────── + cs-req ──▶ codestable/requirements/{slug}.md capability vision + cs-domain ──▶ codestable/requirements/CONTEXT.md domain glossary + codestable/requirements/adrs/NNN-*.md ADRs (3-criteria gate) + CONTEXT-MAP.md present → nest per bounded context +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + Layer 2 · Planning ("how we plan to deliver this big thing next") +─────────────────────────────────────────────────────────────────────── + cs-roadmap ──▶ codestable/roadmap/{slug}/ + Turn "I want X" into a complete up-front plan: + ① High-level design — module / component split + ② Architectural detail — interface contracts + ③ Sub-features — broken into executable units + ② is a hard input for feature-design + (Small needs skip this layer and go straight to L3) +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + Discussion entry (optional · enter when fuzzy, route after triage) +─────────────────────────────────────────────────────────────────────── + ┌── case 1 clear enough ──▶ cs-feat-design + cs-brainstorm ────────▶┼── case 2 small + decided ─▶ feature flow + └── case 3 big with one word ─▶ cs-roadmap +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + Layer 3 · Execution flows (pick one per event type) +─────────────────────────────────────────────────────────────────────── + + ▸ Event: new capability ┌──────────┐ + cs-feat-design ─▶ cs-feat-impl ─▶ cs-code-review ─▶ │ features │ + cs-feat-qa ─▶ cs-feat-accept │ /YYYY-…/ │ + cs-feat-ff ──(light lane, skips design/accept)─▶ └──────────┘ + + ▸ Event: fix a defect ┌──────────┐ + cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix ─▶ │ issues │ + cs-code-review │ /YYYY-…/ │ + └──────────┘ + + ▸ Event: code rot (beta) ┌──────────┐ + cs-refactor / cs-refactor-ff ─▶ cs-code-review │refactors │ + │ /YYYY-…/ │ + └──────────┘ +═══════════════════════════════════════════════════════════════════════ + │ + ▼ trigger any time something is worth recording ▼ +═══════════════════════════════════════════════════════════════════════ + Cross-cut · Knowledge sink (compounding engineering) +─────────────────────────────────────────────────────────────────────── + cs-keep ──▶ codestable/compound/YYYY-MM-DD-{slug}.md + plain markdown, no frontmatter, grep to search + ↑ + Next cs-feat-design / cs-issue-analyze + greps compound/ so experience is reused +═══════════════════════════════════════════════════════════════════════ +``` + +**How to read this diagram:** + +- **Vertical = layers**, not strict time order — Layer 1 is refreshed repeatedly, Layer 2 is only entered for big needs +- **Layer 3 is event-driven**: new need → feature flow, bug → issue flow, rot → refactor flow +- **Cross-cut is the flywheel**: any flow can trigger a sink when something is worth keeping; the next round of work reads it back. This is the physical implementation of CodeStable's "compounding" + +`cs-code-review` is the cross-cutting quality gate at the tail of the feature / issue / refactor execution flows, before commit. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full diagram. --- @@ -136,9 +253,75 @@ See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full diagram. After `/cs-onboard`, a `.codestable/` directory appears at your project root as the aggregate root for requirements, architecture, roadmap, goals, features, issues, refactors, audits, compound, tools, hooks, and reference. -See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints. +``` +your-project/ +├── codestable/ +│ ├── requirements/ # Requirement + domain model (cs-req / cs-domain co-maintain) +│ │ ├── VISION.md # Capability index +│ │ ├── {slug}.md # One file per capability, flat (no grouping) +│ │ ├── CONTEXT.md # Domain glossary (cs-domain, lazy) +│ │ ├── CONTEXT-MAP.md # Multi-context topology (only for multi-context projects) +│ │ ├── adrs/ # Architecture decisions (cs-domain, lazy) +│ │ │ └── NNN-{slug}.md # Nygard 4 sections + status machine +│ │ └── {ctx}/ # Bounded-context subdir (only multi-context) +│ │ ├── CONTEXT.md +│ │ ├── adrs/ +│ │ └── {capability}.md +│ │ +│ ├── roadmap/ # Roadmaps ("how we plan to walk next") +│ │ └── {slug}/ +│ │ ├── {slug}-roadmap.md # Main doc: background / breakdown / sequencing +│ │ ├── {slug}-items.yaml # Machine-readable sub-feature list, acceptance writes status back +│ │ └── drafts/ # Optional: drafts / research +│ │ +│ ├── features/ # Feature flow aggregate root +│ │ └── YYYY-MM-DD-{slug}/ # One directory per feature +│ │ ├── {slug}-brainstorm.md # Optional (cs-brainstorm output) +│ │ ├── {slug}-design.md # Design (cs-feat-design) +│ │ ├── {slug}-checklist.yaml # Progress checklist (impl runs it, accept writes back) +│ │ └── {slug}-acceptance.md # Acceptance report (cs-feat-accept) +│ │ +│ ├── issues/ # Issue flow aggregate root +│ │ └── YYYY-MM-DD-{slug}/ +│ │ ├── {slug}-report.md # Issue report +│ │ ├── {slug}-analysis.md # Root-cause analysis (only when non-obvious) +│ │ └── {slug}-fix-note.md # Fix record +│ │ +│ ├── refactors/ # Refactor flow aggregate root (beta) +│ │ └── YYYY-MM-DD-{slug}/ +│ │ ├── {slug}-scan.md +│ │ ├── {slug}-refactor-design.md +│ │ ├── {slug}-checklist.yaml +│ │ └── {slug}-apply-notes.md +│ │ +│ ├── compound/ # Knowledge sink (compounding engineering), unified directory +│ │ └── YYYY-MM-DD-{slug}.md +│ │ # plain markdown, no frontmatter, grep to search (cs-keep) +│ │ +│ ├── tools/ # Cross-workflow shared scripts (released by onboard) +│ └── reference/ # Shared reference docs (released by onboard) +│ ├── shared-conventions.md # Cross-skill conventions / paths / metadata +│ ├── system-overview.md # CodeStable system overview + scenario routing +│ └── ... +│ +└── AGENTS.md # At project root, not under codestable/ +``` -To change shared conventions, edit the templates under `cs-onboard/reference/`; new projects pick them up at onboard time. +**Key points:** + +- All artifacts aggregate under `codestable/`, so "how did we handle that feature / bug last time" is three seconds away +- `requirements/` is the **long-lived archive** (capability vision + domain glossary CONTEXT.md + decisions adrs/); `roadmap/` is the **planning layer** (what's next) — deliberately separated +- `features/` `issues/` `refactors/` use `YYYY-MM-DD-{slug}/` to bundle all related specs in one directory, no crossing +- `compound/` is the **single** knowledge sink directory — plain markdown, no frontmatter, searched via `grep -r`. Easy to write, easy to find +- `reference/` is copied in by `cs-onboard` from the skill package; to change shared conventions, edit the templates under `cs-onboard/reference/` — new projects pick up the new version on onboard + +### Hard constraint + +> A skill is an independent install unit. At runtime, **each skill can only see files inside its own package**. References like `B-skill/reference/xxx.md` written in skill A's SKILL.md are **simply unreachable** at runtime. +> +> Cross-skill shared references must go through the "working project" layer: `cs-onboard` copies them from the skill package to the project's `codestable/reference/`, and other skills read them via the project-relative path. + +To change shared conventions, edit the templates under `cs-onboard/reference/`; new projects pick them up at onboard time. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full directory model and cross-skill reference constraints. --- diff --git a/README.md b/README.md index f4087e2..9dd6ec3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

Status - CodeStable Skills + CodeStable Skills License

@@ -96,13 +96,13 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 | 实体 | 英文 | 干什么 | |------|------|--------| -| **需求** | requirements | 原始用户故事、当时的讨论与权衡。最终的逃生通道——代码烂成一坨屎时，可以摒弃所有代码、让 AI 重新生成 | -| **架构** | architecture | 为实现需求，系统的编排层长什么样。文档要尽可能精简、统一，**给人读的**，不是给 AI 自嗨的 | +| **需求** | requirements | 原始用户故事 + 领域术语（CONTEXT.md）+ 架构决策（ADR）。最终的逃生通道——代码烂成一坨屎时，可以摒弃所有代码、让 AI 重新生成 | | **路线图** | roadmap | "我想要一个权限校验系统"——直接塞 feature AI 接不住，先拆成路线图分步推进 | | **目标** | goals | 限定起点和终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收 | | **特性** | feature | 实际落地的工程执行过程，人与 AI 共同协作，对 design / 实现 / 验收负责 | | **问题** | issue | 开发完成后的 BUG 单子，AI 和人一同解决 | -| **知识** | compound | 复利工程的知识库，沉淀踩过的坑、好做法、技术决策 | +| **重构** | refactor | 代码腐化时的整理过程（beta） | +| **知识** | compound | 复利工程的知识库，沉淀踩过的坑、好做法、调研结论 | ### 流程 @@ -122,6 +122,32 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 ## 技能总览 + + + + + + + + + + + + + + + + + + + + + + + + +
分组技能用途
根入口cs统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它
接入cs-onboard把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库
需求 & 领域cs-req整理 / 沉淀能力愿景 doc
cs-domain维护 requirements/CONTEXT.md 术语表 + requirements/adrs/ 架构决策（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑
路线图cs-roadmap承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单
讨论入口cs-brainstorm想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap
目标cs-goal限定起点/终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收
特性流程cs-feat新特性子流程入口
cs-feat-design起草 {slug}-design.md 作为后续唯一输入
cs-feat-impl按 design 的推进顺序写代码
cs-code-review实现完成后、commit 前的横切只读代码审查 gate，产 {slug}-review.md
cs-feat-accept逐层对照 design 核对实现，做完整验收闭环
cs-feat-ff超轻量通道：不写 design、不分阶段，让 AI 直接做
问题流程cs-issue问题修复子流程入口
cs-issue-report把脑子里的问题落成可复现、可追溯的 report
cs-issue-analyze找根因、评估修复风险、给方案
cs-issue-fix定点修复 + 验证 + 写 fix-note
重构流程cs-refactor(beta) 重构主流程
cs-refactor-ff(beta) 轻量重构通道
知识沉淀cs-keep坑点 / 技巧 / 决策 / 调研沉淀到 compound/，纯 markdown，grep 检索
对外文档cs-doc-tutorial对外的开发者指南 / 用户指南（任务导向，怎么用 X 做 Y）
cs-doc-api从源码反推的 API 参考（逐条目，给读者查零件）
+ 完整技能目录见 [SKILL_CATALOG.md](./SKILL_CATALOG.md)。日常不知道用哪个时直接调用 `/cs`，它会按诉求路由到对应技能。 --- @@ -130,7 +156,98 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：根入口路由、onboard、长效档案、roadmap 规划、feature / issue / refactor 执行流，以及横切的知识沉淀。 -完整示意图见 [WORKFLOW.md](./WORKFLOW.md)。 +``` +═══════════════════════════════════════════════════════════════════════ + 根入口 · 路由 （任何时刻都可以调用） +─────────────────────────────────────────────────────────────────────── + cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能 + （本身不做事，只做分诊和提示） +═══════════════════════════════════════════════════════════════════════ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + （未接入） （已接入） （想了解体系） + 走阶段 0 直达 1~4 层 / 横切 给速读 + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + 阶段 0 · 接入 （只在新项目跑一次） +─────────────────────────────────────────────────────────────────────── + cs-onboard ──▶ 生成 codestable/ 骨架 + 释放 reference/、tools/ +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + 第 1 层 · 长效档案（"系统现在长什么样"，只记现状） +─────────────────────────────────────────────────────────────────────── + cs-req ──▶ codestable/requirements/{slug}.md 能力愿景 + cs-domain ──▶ codestable/requirements/CONTEXT.md 领域术语 + codestable/requirements/adrs/NNN-*.md 架构决策（守门 3 判据） + CONTEXT-MAP.md 存在时按子 context 嵌套 +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + 第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要） +─────────────────────────────────────────────────────────────────────── + cs-roadmap ──▶ codestable/roadmap/{slug}/ + 把一个"我想要 X 系统"做成完整的事前规划： + ① 概设 —— 拆成哪几个模块 / 组件 + ② 架构层详设 —— 模块间接口契约 / 共享协议 + ③ 子 feature —— 把方案分解成多条可执行的 feature + ② 是 feature-design 的硬约束输入 + （小需求可跳过本层，直接进第 3 层） +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + 讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游） +─────────────────────────────────────────────────────────────────────── + ┌── case 1 已经够清楚 ──▶ cs-feat-design + cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md） + └── case 3 大需求只有一个词 ─▶ cs-roadmap +═══════════════════════════════════════════════════════════════════════ + │ + ▼ +═══════════════════════════════════════════════════════════════════════ + 第 3 层 · 执行流程（按事件类型选一条进入） +─────────────────────────────────────────────────────────────────────── + + ▸ 事件：新增能力 ┌──────────┐ + cs-feat-design ─▶ cs-feat-impl ─▶ cs-code-review ─▶ │ features │ + cs-feat-qa ─▶ cs-feat-accept │ /YYYY-…/ │ + cs-feat-ff ──(轻量直通车，跳过 design/accept)─▶ └──────────┘ + + ▸ 事件：修复缺陷 ┌──────────┐ + cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix ─▶ │ issues │ + cs-code-review │ /YYYY-…/ │ + └──────────┘ + + ▸ 事件：代码腐化（beta） ┌──────────┐ + cs-refactor / cs-refactor-ff ─▶ cs-code-review │refactors │ + │ /YYYY-…/ │ + └──────────┘ +═══════════════════════════════════════════════════════════════════════ + │ + ▼ 任意阶段觉得"这个值得记下来"都能触发 ▼ +═══════════════════════════════════════════════════════════════════════ + 横切层 · 知识沉淀（复利工程） +─────────────────────────────────────────────────────────────────────── + cs-keep ──▶ codestable/compound/YYYY-MM-DD-{slug}.md + 纯 markdown，无 frontmatter，grep 检索 + ↑ + 下一次 cs-feat-design / cs-issue-analyze + 会回头 grep compound/，让经验在新工作里被复用 +═══════════════════════════════════════════════════════════════════════ +``` + +**怎么读这张图：** + +- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入 +- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流 +- **横切层是飞轮**：任何流程跑完发现"这事值得记下来"都可以触发沉淀，沉淀的产物又会被下一次同类工作读到——这是 CodeStable "复利"的物理实现 + +`cs-code-review` 是 feature / issue / refactor 执行流末端、commit 前的横切质量门禁。完整示意图见 [WORKFLOW.md](./WORKFLOW.md)。 --- @@ -138,6 +255,76 @@ CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动** `/cs-onboard` 跑完后，会在你的项目根下生成 `.codestable/`，作为 requirements、architecture、roadmap、goals、features、issues、refactors、audits、compound、tools、hooks 和 reference 的聚合根。 +``` +你的项目/ +├── codestable/ +│ ├── requirements/ # 需求 + 领域模型（cs-req / cs-domain 共同维护） +│ │ ├── VISION.md # 能力中心索引 +│ │ ├── {slug}.md # 一个能力一份，扁平不分组 +│ │ ├── CONTEXT.md # 领域术语表（cs-domain，lazy） +│ │ ├── CONTEXT-MAP.md # 多 context 拓扑入口（仅多 context 项目） +│ │ ├── adrs/ # 架构决策记录（cs-domain，lazy） +│ │ │ └── NNN-{slug}.md # Nygard 四节 + 状态机 +│ │ └── {ctx}/ # 子 context 子目录（仅多 context） +│ │ ├── CONTEXT.md +│ │ ├── adrs/ +│ │ └── {capability}.md +│ │ +│ ├── roadmap/ # 路线图（"接下来打算怎么走"） +│ │ └── {slug}/ +│ │ ├── {slug}-roadmap.md # 主文档：背景 / 拆解 / 排期 +│ │ ├── {slug}-items.yaml # 机器可读子 feature 清单，acceptance 回写状态 +│ │ └── drafts/ # 可选：草稿 / 调研 +│ │ +│ ├── features/ # 特性流程聚合根 +│ │ └── YYYY-MM-DD-{slug}/ # 一个 feature 一个目录 +│ │ ├── {slug}-brainstorm.md # 可选（cs-brainstorm 产出） +│ │ ├── {slug}-design.md # 方案（cs-feat-design） +│ │ ├── {slug}-checklist.yaml # 推进清单（impl 跑、accept 回写） +│ │ └── {slug}-acceptance.md # 验收报告（cs-feat-accept） +│ │ +│ ├── issues/ # 问题流程聚合根 +│ │ └── YYYY-MM-DD-{slug}/ +│ │ ├── {slug}-report.md # 问题报告 +│ │ ├── {slug}-analysis.md # 根因分析（不显然时才有） +│ │ └── {slug}-fix-note.md # 修复记录 +│ │ +│ ├── refactors/ # 重构流程聚合根（beta） +│ │ └── YYYY-MM-DD-{slug}/ +│ │ ├── {slug}-scan.md +│ │ ├── {slug}-refactor-design.md +│ │ ├── {slug}-checklist.yaml +│ │ └── {slug}-apply-notes.md +│ │ +│ ├── compound/ # 知识沉淀（复利工程）统一目录 +│ │ └── YYYY-MM-DD-{slug}.md +│ │ # 纯 markdown，无 frontmatter，grep 检索（cs-keep 产出） +│ │ +│ ├── tools/ # 跨工作流共享脚本（onboard 释放） +│ └── reference/ # 共享参考文档（onboard 释放） +│ ├── shared-conventions.md # 跨技能口径 / 路径命名 / 元数据规范 +│ ├── system-overview.md # CodeStable 体系总览 + 场景路由 +│ └── ... +│ +└── AGENTS.md # 在项目根，不在 codestable/ 里 +``` + +**几条要点：** + +- 所有产物都聚在 `codestable/` 下，让"上次那个 feature / bug 当时怎么搞的"三秒能找到 +- `requirements/` 是**长效档案**（能力愿景 + 领域术语 CONTEXT.md + 拍板决策 adrs/），`roadmap/` 是**规划层**（接下来怎么走），两者刻意分开 +- `features/` `issues/` `refactors/` 用 `YYYY-MM-DD-{slug}/` 一个目录装齐所有相关 spec，不交叉 +- `compound/` 是**唯一**的知识沉淀目录，纯 markdown 无 frontmatter，靠 `grep -r` 检索——好写好搜 +- `reference/` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `cs-onboard/reference/` 模板，新项目 onboard 自动带上新版 + +### 硬约束 + +> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**。 +> +> 跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `codestable/reference/`，其他 skill 用项目相对路径读取。 + +要改共享口径，改 `cs-onboard/reference/` 下的模板，新项目 onboard 时带上新版本。 + 完整目录说明和跨 skill 引用约束见 [WORKFLOW.md](./WORKFLOW.md)。 --- diff --git a/browser-bridge/SKILL.md b/browser-bridge/SKILL.md index f2c65ce..b80ec83 100644 --- a/browser-bridge/SKILL.md +++ b/browser-bridge/SKILL.md @@ -15,6 +15,7 @@ Browser Bridge 是一个独立技能。它只说明自己的安装方式、命 - Python 依赖和 Chrome 扩展已经安装。 - `python /scripts/browser.py tabs` 能看到浏览器 tab。 +- 频繁执行命令时，先启动常驻 master，避免每次 CLI 调用都等待扩展重连。 ## 架构 @@ -52,6 +53,22 @@ pip install bs4 simple-websocket-server bottle requests 下面的 `` 指包含本 `SKILL.md` 的目录。 +### 推荐：启动常驻 master + +如果直接反复调用 `browser.py exec ...`，每个短命 CLI 进程都可能重新启动 bridge server，并等待 Chrome 扩展重连，通常会多出数秒冷启动时间。频繁操作浏览器时，先单独启动： + +```bash +python /scripts/browser_master.py +``` + +保持这个进程运行。之后正常使用 `browser.py exec`、`scan`、`tabs` 等命令，它们会自动通过 `http://127.0.0.1:18766/link` 转发到常驻 master。 + +只需要 JS 返回值、不需要 DOM diff 和 toast 捕获时，给 `exec` 加 `--no-monitor`： + +```bash +python /scripts/browser.py exec --no-monitor "document.title" +``` + ### exec: 在浏览器里执行 JavaScript 这是最常用的主命令。直接写 JavaScript 查询或操作 DOM。系统会捕获返回值、DOM 变化和执行期间出现的短暂文本，例如 toast、通知、loading 文案。 diff --git a/browser-bridge/scripts/browser_master.py b/browser-bridge/scripts/browser_master.py new file mode 100644 index 0000000..a3f8c84 --- /dev/null +++ b/browser-bridge/scripts/browser_master.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python3 +""" +Persistent Browser Bridge master. + +Keep this process running to avoid the 5-10s cold-start cost of invoking +browser.py directly for every command. Regular browser.py calls will detect the +HTTP link on port+1 and forward commands to this process. +""" + +import argparse +import json +import threading + +from tmwd_bridge.TMWebDriver import TMWebDriver + + +def main(): + parser = argparse.ArgumentParser(description="Run a persistent Browser Bridge master") + parser.add_argument("--host", default="127.0.0.1") + parser.add_argument("--port", type=int, default=18765) + args = parser.parse_args() + + TMWebDriver(host=args.host, port=args.port) + print(json.dumps({ + "status": "success", + "msg": "browser bridge master started", + "ws": f"ws://{args.host}:{args.port}", + "http": f"http://{args.host}:{args.port + 1}/link", + }), flush=True) + + try: + threading.Event().wait() + except KeyboardInterrupt: + print(json.dumps({"status": "stopped"}), flush=True) + + +if __name__ == "__main__": + main() diff --git a/browser-bridge/scripts/tmwd_bridge/__init__.py b/browser-bridge/scripts/tmwd_bridge/__init__.py index e8882a2..73883ef 100644 --- a/browser-bridge/scripts/tmwd_bridge/__init__.py +++ b/browser-bridge/scripts/tmwd_bridge/__init__.py @@ -48,14 +48,12 @@ def init_browser(host='127.0.0.1', port=18765, wait=True): _driver = TMWebDriver(host=host, port=port) if wait: for i in range(20): - time.sleep(1) sess = _driver.get_all_sessions() if len(sess) > 0: break + time.sleep(1) if len(_driver.get_all_sessions()) == 0: _log("[CS] Warning: No browser tabs connected. Make sure the extension is installed.") - elif len(_driver.get_all_sessions()) == 1: - time.sleep(3) return _driver @@ -101,10 +99,13 @@ def web_execute_js(script, switch_tab_id=None, no_monitor=False, wait_selector=N suggestion: Hint about what happened (e.g. "页面无明显变化") """ driver = get_driver() - if len(driver.get_all_sessions()) == 0: + sessions = driver.get_all_sessions() + if len(sessions) == 0: return {"status": "error", "msg": "No browser tabs available. Is the extension connected?"} if switch_tab_id: driver.default_session_id = switch_tab_id + elif driver.default_session_id is None and sessions: + driver.default_session_id = str(sessions[0].get('id')) if wait_selector: wait_js = f'await new Promise((resolve, reject) => {{ const start = Date.now(); const check = () => {{ const el = document.querySelector({json.dumps(wait_selector)}); if (el) return resolve(el); if (Date.now() - start > {wait_ms}) return reject(new Error("Timeout waiting for: " + {json.dumps(wait_selector)})); setTimeout(check, 200); }}; check(); }});' script = wait_js + '\n' + script @@ -147,6 +148,8 @@ def web_scan(tabs_only=False, switch_tab_id=None, text_only=False, size_only=Fal return {"status": "error", "msg": "No browser tabs available. Is the extension connected?"} if switch_tab_id: driver.default_session_id = switch_tab_id + elif driver.default_session_id is None and sessions: + driver.default_session_id = str(sessions[0].get('id')) if wait_selector: wait_result = simphtml.execute_js_rich( f'await new Promise((resolve, reject) => {{ const start = Date.now(); const check = () => {{ const el = document.querySelector({json.dumps(wait_selector)}); if (el) return resolve(el); if (Date.now() - start > {wait_ms}) return reject(new Error("Timeout waiting for: " + {json.dumps(wait_selector)})); setTimeout(check, 200); }}; check(); }});', diff --git a/cs-arch/SKILL.md b/cs-arch/SKILL.md deleted file mode 100644 index abb805c..0000000 --- a/cs-arch/SKILL.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -name: cs-arch -description: 维护 `.codestable/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 cs-roadmap）。 ---- - -# cs-arch - -## 启动必读 - -开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 - -`.codestable/architecture/` 是项目"地图"——design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。本技能是"起草 / 刷新 / 体检"三件事的统一入口。 - -**architecture 是累积的、自给自足的系统地图**，不是某次 feature 的详细方案，而是所有已落地 feature 沉淀下来的"系统现在长什么样"总图。读者打开应能看懂整体结构而不需要跳回历史 design。design 是临时增量稿，acceptance 把稳定下来的名词 / 编排 / 约束提炼回这里；design 文件归档，只在追究具体决策细节时翻。 - -**只记现状不记计划**——默认在 acceptance 跟着代码同步，必要时本技能主动 backfill / update。**不写"未来会加什么层"、"下一步打算拆出 X 模块"**——那些归 `cs-roadmap`。用户说"我想重构成 X 架构"先走 roadmap 拆 feature，每次 acceptance 把实际达到的结构提炼回 architecture。 - -详略判据：**够不够让读者不跳转就读懂系统**——稳定、跨 feature 可见的那一层写全；模块内部循环、辅助函数、一次性实现决定不进来。 - -架构文档价值在**准、稳、可查**。AI 容易破坏这三点的几种问题： - -- **凭空造系统**——文档说 `AuthManager 协调 TokenService`，代码里根本没 `AuthManager` -- **替用户拍板**——悄悄选某种分层方式，读者以为是既定事实 -- **代码复述**——每节都说"这里有什么"，不说"为什么这么分"，信息量等于 `ls -R` -- **检查时看一眼感觉没问题**——没给具体位置证据 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。文档结构模板、check 覆盖项、报告格式看同目录 `reference.md`。 - ---- - -## 模式分流 - -启动先判断模式三选一（不让用户选菜单）： - -| 用户说什么 | 模式 | -|---|---| -| "刷新 {某文档}"、"代码变了把架构 doc 同步"、"更新到最新" | `update` | -| "检查 design 自洽"、"方案和代码对得上吗"、"几份文档有没有打架"、"做架构体检" | `check` | -| "补一份架构 doc"、"这块模块一直没写档"、"把已经在跑的子系统结构写下来" | `backfill` | - -判断不出问用户。用户说"我想重构成 X / 打算新做 Y 模块"——不是本技能的事，转 `cs-roadmap`。 - ---- - -## 单目标规则 - -每次只跑一个模式，且只锁定一个目标： - -- `backfill`：给已存在但从没写过档的模块补一份（`architecture/{type}-{slug}.md` 或更新 `ARCHITECTURE.md`） -- `update`：按代码最新状态 + 用户素材刷新一份已有 doc -- `check`：三个子目标之一 - - `design-internal` — 一份 design 内部一致性 - - `design-vs-code` — design 与代码一致性 - - `architecture-folder-internal` — `architecture/` 多份文档间一致性 - -为什么不一次做多件？起草时一次吐多份用户 review 不过来；检查时三个子目标视角和材料完全不同，同时做每边都不深。用户提多个目标让 TA 选一个。 - ---- - -## 工作流骨架（三模式共用 6 阶段） - -``` -Phase 1：锁定目标 -Phase 2：读取材料 -Phase 3：执行（backfill/update = 起草；check = 检查） -Phase 4：自查（backfill/update）或 输出报告（check） -Phase 5：用户 review -Phase 6：落盘（backfill/update）或 等用户拍板（check） -``` - -### Phase 1：锁定目标 - -确认：模式 + 目标对象 + 范围。 - -- backfill：新 slug + 受众 + 范围（+ 确认模块在代码里已存在） -- update：已有文档路径 -- check：子目标 + 检查对象（feature 名 / architecture 子范围） - -范围不收敛就问用户收敛——一份 doc"全模块重写"往往意味着底下其实有多个独立子系统应该拆；一次检查覆盖整个 `architecture/` 报告读起来抓不到重点。 - -### Phase 2：读取材料 - -**共同必读**：`shared-conventions.md` + `ARCHITECTURE.md` + `architecture/` 下其他文档。 - -**backfill / update 额外**（详见 `reference.md` "读取清单"）：目标模块代码入口和核心文件 + 用户素材 + 相关 compound 沉淀（decision / explore / learning）+ 相关已有 feature 方案。**update 专项**：当前 doc 全文 + `last_reviewed` 之后的代码变更（`git log` 粗扫）。 - -**check 额外**（按子目标）： -- `design-internal` / `design-vs-code`：方案 doc 全文 + 架构相关 doc -- `design-vs-code` 再额外：与 design 第 2/3 节直接对应的代码 -- `architecture-folder-internal`：用户圈定的几份 doc + 索引 + 顺藤摸到的被引用文档（不扩展到代码） - -### Phase 3：执行 - -**backfill / update**：按 `reference.md` "文档结构"写**完整初稿**不分批吐半成品——分批 review 用户看不到全局一致性，第 2 节描述的结构和第 4 节决策经常有跨节矛盾。 - -**check**：按 `reference.md` "检查覆盖项"（三个子目标各 6 类）逐条执行。每条不一致都要记**可定位位置**（`file:line` 或 `design 第X节`）+ 现象 + 影响 + 修复建议。 - -### Phase 4：自查 / 输出报告 - -**backfill / update**：按 `reference.md` "自查清单"（7 条）就地跑一遍，发现问题在 review 前处理掉（删 / 标 TODO / 改写）。自查结果简短汇报——发现了就说，不要走过场。 - -**check**：按 `reference.md` "报告模板"输出完整报告（检查摘要 / 不一致清单带严重级别 / 观察项 / 一致性良好项 / 建议下一步）。 - -### Phase 5：用户 review - -**backfill / update**：完整初稿贴给用户 review。 -**check**：报告给用户，等确认结论。本技能不替用户拍板。 - -### Phase 6：落盘 / 结束 - -**backfill**： - -- 写入 `architecture/{type}-{slug}.md`（命名规则见 `shared-conventions.md` 第 0 节），frontmatter `status: current`、`last_reviewed` 填当天 -- **同类聚合检查**（落盘前必跑）：按"架构 doc 分组规则"判断本次落盘后某 type 在根目录 ≥6 份——命中就把这类全搬进 `architecture/{type}/`、去掉文件名前缀、同步改 `ARCHITECTURE.md` 链接；搬迁清单在 Phase 5 一并 review -- **索引更新**：`ARCHITECTURE.md` 加新文档引用——backfill **必定**要加，否则写了没人会读；改动同样 review，不偷偷改 - -**update**：覆盖已有文件，`last_reviewed` 更新当天；结构性改动大时文末 `变更日志` 节加一条；`ARCHITECTURE.md` 只在 scope/summary 影响索引描述时更新。 - -**check**：不落盘结束。用户可能基于报告决定触发 backfill/update——那是下一轮的事。 - ---- - -## 硬性边界 - -1. **只锚代码不造系统**（backfill/update）——每条结构化断言必须能锚到 `file:line`；锚不到标 `TODO: 待确认`。模块在代码里还没写就不该走 backfill —— 那是规划转 `cs-roadmap` -2. **不替用户拍板决策**（backfill/update）——关键决策节实质内容必须来自用户或可追溯的 decision，AI 只起草结构和串联语言 -3. **只检查不修复**（check）——禁止改 design / 代码 / 配置。check 和修复分开做，用户才能看到完整不一致清单后整体决定优先级 -4. **证据化**（check）——每条不一致有可定位位置 -5. **可执行建议**（check）——具体到"改哪里、怎么改"，但不落盘 -6. **单目标**（所有模式） -7. **不改代码、不动 spec**（所有模式）——只写架构 doc 或出报告。发现代码 / 方案 / decision 有问题记成"观察项" -8. **不发散**——范围外问题不扩展，记观察项 - ---- - -## 退出条件 - -**共通**： -- [ ] 已锁定单一模式和单一目标 -- [ ] 用户明确 review 通过（backfill/update）或确认结论（check） -- [ ] 没有顺手修改代码 / 方案 doc / decision -- [ ] 没有范围外文档改动 - -**backfill / update 额外**： -- [ ] 自查清单逐条跑过并汇报处理 -- [ ] frontmatter 完整（`doc_type: architecture` / `status` / `last_reviewed`） -- [ ] 每个结构化断言有 `file:line` 锚点或标 `TODO: 待确认` -- [ ] 落盘前已按"分组规则"判断同类 ≥6 份，命中则搬迁清单已 review -- [ ] **backfill**：`ARCHITECTURE.md` 已加链接（或用户明确决定暂不加） -- [ ] **update**：结构性改动有 `变更日志` 条目 - -**check 额外**： -- [ ] 已覆盖对应子目标的检查项 -- [ ] 报告含不一致清单 + 修复建议 -- [ ] 报告不含任何实际修复动作 - ---- - -## 和其他工作流的关系 - -| 方向 | 关系 | -|---|---| -| `cs-req` 配合 | req 写"为什么有这个能力"、本技能写"用什么结构实现"；frontmatter `implements` 反向链到 req slug | -| `cs-feat-design` 上游 | design 写"本 feature 和哪块架构对接"时读本技能产出的 doc；design 写完可触发 check 体检 | -| `cs-feat-accept` 下游 | 验收阶段实际去更新本技能产出的 doc（acceptance 自己归并，不回调本技能）；想确认实现 vs design 对得上时触发 check `design-vs-code` | -| `cs-decide` 配合 | 拍板架构决策后，update 模式把引用补进相关 doc 第 4 节 | -| `cs-issue-analyze` 读者 | 根因分析读本技能 doc 定位模块边界 | -| `cs-onboard` 创建者 | onboard 建 `ARCHITECTURE.md` 占位，之后由本技能填实 | -| `cs-roadmap` 配合 | architecture 记现状、roadmap 记规划。roadmap 起草读本技能 doc 理解现状但不改它；目标态架构归 roadmap | - ---- - -## 常见错误 - -**backfill / update**： -- 把"打算重构成什么样"写进来——目标态归 roadmap -- 凭空造系统——出现代码里不存在的"协调层 / 中枢 / 管理器" -- 替用户拍板——选型理由是 AI 编的 -- 代码复述——每节只列"这里有什么"，没说"为什么这么分" -- 分批吐半成品——用户看不出跨节矛盾 -- 术语冲突——新名字和代码 / 其他 architecture doc / compound 已有的冲突 -- 一次写 / 改多份——审不过来全部粗糙合入 -- 和已有 decision 冲突不停下——自己写了一版相悖的说法 -- backfill 落盘后忘加 `ARCHITECTURE.md` 索引——写了没人能发现 -- 把还没在代码里跑起来的模块走 backfill——那是目标态转 roadmap -- update 加新内容但没代码依据——内容飘离实际的开端 -- 顺手把代码 / 方案 doc 一起改了——越界 -- 同类 ≥6 份还往根目录平铺——触发分组规则没搬迁 -- 文件名没遵循 `{type}-{slug}.md`——分组规则形同虚设 - -**check**： -- 一次同时做多个子目标 -- `architecture-folder-internal` 顺手读代码——那是 `design-vs-code` -- 发现问题就顺手改代码或文档 -- 只说"这里不太对"不给证据位置 -- 建议过于抽象（"优化一下架构"） -- 从一个目标无限扩展到全仓库审计 diff --git a/cs-arch/reference.md b/cs-arch/reference.md deleted file mode 100644 index adfd8e3..0000000 --- a/cs-arch/reference.md +++ /dev/null @@ -1,173 +0,0 @@ -# cs-arch 参考模板 - -SKILL.md 只保留流程骨架，具体格式 / 覆盖项 / 报告模板都在这里。 - ---- - -## 1. 架构文档结构（backfill / update 产出） - -### 1.1 frontmatter - -```yaml ---- -doc_type: architecture -slug: {英文连字符；和文件名一致} -scope: {一句话覆盖范围} -summary: {一句话总结要点} -status: current | draft | outdated -last_reviewed: YYYY-MM-DD -tags: [] -depends_on: [] # 其他 architecture doc 的 slug，可选 -implements: [] # 承载的 requirement slug 列表，可空——纯基础设施 / 工具层没有对应 req 是正常的 ---- -``` - -### 1.2 正文节 - -```markdown -## 0. 术语 - -首次引入的专有名词简要定义 + 和相近名词的区分（"本文里 X 指 Y，和代码里的 X' 不是同一个东西"）。没有新术语就省略。 - -## 1. 定位与受众 - -- 项目里哪一块（模块 / 子系统 / 跨模块关注点） -- 谁会读（feature-design / issue-analyze / 新人上手） -- 读完能干嘛（定位代码 / 了解对外接口 / 知道约束） - -## 2. 结构与交互 - -- 模块怎么划分、依赖方向 -- 对外接口、对内接口 -- 跨模块契约（数据格式 / 调用协议 / 状态归属） -- 模块 ≤ 2 或关系线性时不画图；否则建议 Mermaid - -每条结构化断言后附 `file:line` 锚点，或在节末"代码锚点"小节集中给。 - -## 3. 数据与状态 - -- 关键类型 / 核心数据结构（简述 + 定义位置 file:line） -- 所有权归属（谁写谁读） -- 持久化边界（内存 / 本地 / 数据库 / 外部服务） - -## 4. 关键决策 - -不是决策全文，是**引用**——每条一两行：结论一句话 + 引用（`compound/YYYY-MM-DD-decision-{slug}.md` 或用户原话出处）+ 为什么引用到这份 doc 里。 - -没有已落档的决策就省略，或记 `TODO: 某决定应沉淀为 decision`。 - -## 5. 代码锚点 - -"想看代码从哪看"清单：入口文件 / 关键函数 / 关键类型定义。格式：`{file}:{function/class} — 一行说明`。 - -## 6. 已知约束 / 边界情况 - -本模块"不能动 / 动了要小心"的硬约束 + 来源（attention.md / decision / learning 等）。 - -## 7. 相关文档 - -依赖的其他 architecture doc / 承载的 requirement / 相关 decision / learning / trick / explore / 使用本模块的代表性 feature design。 - -## 变更日志（update 模式才有） - -- YYYY-MM-DD：{一句话描述} -``` - ---- - -## 2. backfill / update 自查清单 - -每条针对一种 AI 默认会犯的错： - -1. **每个结构化断言能不能锚到代码？**——锚不到的删掉或标 `TODO: 待确认` -2. **有没有替用户拍板？**——"关键决策"节是引用已有 decision / 用户原话，还是 AI 编的选型理由？后者一律不许进 -3. **有没有变成代码复述？**——每节至少一句"为什么这么分"，没有这句的节基本就是 `ls` 贴文字 -4. **术语冲突检查做了吗？**——新引入的架构术语 grep（代码、`architecture/` 下所有文档、`compound/`）。冲突就换名或在第 0 节明确区分 -5. **是否和现有 architecture / decision 冲突？**——发现冲突不许"写自己那版"，要么引用要么停下来问用户 -6. **单节长度**——超过 1 屏就该砍或拆 -7. **update 专项**：本次新加 / 改动的段落都有代码变化作为依据？凭空"加听起来更完整的描述"是飘离实际的开端 - ---- - -## 3. check 模式覆盖项 - -三个子目标各覆盖 6 类。 - -### 3.1 design-internal（一份 design 内部一致性） - -1. **术语一致性**——第 0 节定义的术语后面有没有被同义词替换或语义漂移 -2. **需求对齐**——第 1 节摘要自洽，没偏离已确认目标 -3. **契约闭环**——第 2 节契约示例在第 3 节有对应改动计划 -4. **示例与决策一致**——契约示例行为是否与关键决策矛盾 -5. **范围守护**——改动计划没超出"明确不做" -6. **推进可执行性**——推进步骤能验证、依赖前后无矛盾 - -### 3.2 design-vs-code（design 与代码对得上） - -1. **类型一致性**——design 定义的核心类型 / 字段，代码里存在且语义一致 -2. **行为一致性**——design 声明的输入→输出对得上代码实际行为 -3. **写路径一致性**——design 声明的写入口，代码没有额外旁路写入 -4. **边界行为一致性**——design 的异常 / 边界规则代码有实现 -5. **改动边界一致性**——代码没越界或漏实现 -6. **推进结果一致性**——每步退出信号对应代码状态可验证 - -### 3.3 architecture-folder-internal（多份文档间一致性） - -1. **术语一致性**——同概念称呼统一，无同义词漂移或同名异义 -2. **模块边界一致性**——A 说某职责归模块 X，B 是不是也这么说；有没有两份都声称拥有同一块职责 -3. **跨文引用有效性**——`see xxx.md` / `定义见 yyy.md` 引用的目标真的存在 -4. **接口 / 契约对齐**——多份涉及同一接口 / 类型时签名 / 字段 / 语义一致 -5. **依赖关系闭环**——A 声明依赖 B 提供的能力，B 真的暴露了；有没有单向悬空依赖 -6. **同类聚合与命名**——同 type 文档遵循 `{type}-{slug}.md`，根目录某 type ≥6 份是否还平铺（参照 `shared-conventions.md`） - ---- - -## 4. check 模式报告模板 - -```markdown -# 架构一致性检查报告 - -> 目标: design-internal | design-vs-code | architecture-folder-internal -> 范围: {feature}/{模块}/{章节范围} -> 日期: YYYY-MM-DD -> 结论: pass | pass-with-risk | fail - -## 1. 检查摘要 - -一句话总结。 - -## 2. 不一致清单 - -| ID | 严重级别 | 位置 | 现象 | 影响 | 建议修复 | -|---|---|---|---|---|---| -| AC-01 | 高/中/低 | `{文件}:{行号}` 或 `design 第X节` | 描述 | 后果 | 修复建议（不执行） | - -## 3. 观察项（范围外，不动手） - -读 `architecture/` 时发现的结构性问题：某个 type ≥6 份仍平铺（应触发 `update` 搬迁）；文件名没遵循 `{type}-{slug}.md`；其他顺带看到的不合理点。没有就省略本节。 - -## 4. 一致性良好项 - -列 2-5 条检查通过的关键点——只有负面信息的报告让用户失去对系统的整体信心。 - -## 5. 建议下一步 - -- **fail**：建议先修哪几条再重跑 -- **pass-with-risk**：实现 / 验收阶段重点回归哪些点 -- **pass**：可进下一阶段 -``` - -**严重级别**： - -- **高**：让实现走错方向，或代码已和 design 实质偏离（漏实现关键契约 / 行为相反 / 术语指代不同的东西） -- **中**：能猜出意图但留有歧义（同义词漂移 / 契约示例和决策表面对得上但细节冲突 / 退出信号说不清） -- **低**：表述别扭或可读性问题，不影响理解 - ---- - -## 5. compound 检索命令（backfill / update 用） - -```bash -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter "doc_type=decision|explore|learning" --query "{模块关键词}" -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter status=active --query "{模块关键词}" -``` diff --git a/cs-audit/SKILL.md b/cs-audit/SKILL.md index b9368fe..9a17a16 100644 --- a/cs-audit/SKILL.md +++ b/cs-audit/SKILL.md @@ -9,7 +9,7 @@ description: 系统审计——从代码中主动发现 bug 隐患、安全漏 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 -`cs-issue` 等你报 bug，`cs-refactor` 等你指优化点，`cs-explore` 等你提问题——但"我也不知道哪有问题，你先扫一遍看看"这个诉求没人接。`cs-audit` 补上这块：**在用户限定的范围内主动扫描，产出一份按严重度 × 性质交叉分类的发现清单**。 +`cs-issue` 等你报 bug，`cs-refactor` 等你指优化点，`cs-keep` 等你说"这事记一下"——但"我也不知道哪有问题，你先扫一遍看看"这个诉求没人接。`cs-audit` 补上这块：**在用户限定的范围内主动扫描，产出一份按严重度 × 性质交叉分类的发现清单**。 本技能只发现、不定修。修是 `cs-issue` / `cs-refactor` 的事。 @@ -74,7 +74,7 @@ description: 系统审计——从代码中主动发现 bug 隐患、安全漏 - **安全**：注入风险、敏感数据暴露、权限校验缺失、不安全依赖 - **性能**：N+1 查询、重复计算、无缓存热点路径、内存泄漏、无分页全量加载 - **可维护性**：超长函数（> 80 行）、圈复杂度 > 15、重复逻辑块、神秘常量、循环依赖 -- **架构偏离**：代码与 `.codestable/architecture/` 记录不一致、分层泄漏、跨模块隐式耦合 +- **架构偏离**：代码违反 `.codestable/requirements/adrs/` 已拍板决策、分层泄漏、跨模块隐式耦合 扫描时用 Glob / Grep / Read 真实读代码。每条发现必须记录 `文件:行号` + 具体代码片段。 @@ -111,8 +111,8 @@ index.md 末尾给优先级建议： |---|---|---| | `cs-issue` | 用户报已知 bug | audit 发现 bug 后建议开 `cs-issue` | | `cs-refactor` | 用户指已知优化点 | audit 发现可优化点后建议开 `cs-refactor` | -| `cs-explore` | 围绕一个问题查代码 | audit 是批量扫多个维度，不等同于 explore | -| `cs-arch` | 维护架构文档 | cs-arch 维护文档，cs-audit 检查代码是否偏离文档 | +| `cs-keep` | 沉淀单点经验 / 决策 | audit 是批量扫多维度发现新问题，cs-keep 是把已知的事写下来 | +| `cs-domain` | 维护 ADR / CONTEXT.md | cs-domain 写决策，cs-audit 检查代码是否偏离已拍板的 ADR | | `cs-security-review` | 安全审查 | audit 的安全维度是轻量扫描，深度安全审查走专项 | --- @@ -124,7 +124,7 @@ index.md 末尾给优先级建议： - **置信度必标**——不准所有发现都标 `high` - **每种维度上限 5 条**——逼 AI 挑最值得报的，不是 dump 所有发现 - **只发现不定修**——cs-audit 不出代码改动。出现"顺便修了"就算越界 -- **架构偏离引用当前文档**——不准凭记忆判断架构应该长什么样，必须读 `.codestable/architecture/` 对照 +- **架构偏离引用 ADR**——不准凭记忆判断架构应该长什么样，必须读 `.codestable/requirements/adrs/` 对照 - **旧审计标注过期**——同名模块新审计覆盖旧审计时，旧 index 标 `status: superseded` + `superseded-by: {新目录}` --- @@ -144,4 +144,4 @@ index.md 末尾给优先级建议： - `reference.md` — index.md / finding-NN.md 模板 - `.codestable/reference/shared-conventions.md` — 跨工作流共享口径 -- `.codestable/architecture/` — 架构偏离类发现对照源 +- `.codestable/requirements/adrs/` — 架构偏离类发现对照源 diff --git a/cs-audit/reference.md b/cs-audit/reference.md index f02dea6..b5d5ce4 100644 --- a/cs-audit/reference.md +++ b/cs-audit/reference.md @@ -124,5 +124,5 @@ status: open ### 架构偏离 - [ ] 分层泄漏：上层直接调下层实现细节、绕过中间层 - [ ] 模块隐式耦合：跨模块直接 import 内部文件（非公开 API） -- [ ] 与 `.codestable/architecture/` 记录不一致 +- [ ] 与 `.codestable/requirements/adrs/` 已拍板决策不一致 - [ ] 约定违背：命名 / 目录结构 / 错误处理模式与项目约定不符 diff --git a/cs-brainstorm/SKILL.md b/cs-brainstorm/SKILL.md index ae426f7..6a6bbed 100644 --- a/cs-brainstorm/SKILL.md +++ b/cs-brainstorm/SKILL.md @@ -34,7 +34,7 @@ brainstorm 是"讨论层"统一入口。 每次都做： -1. **扫一眼仓库**——先读 `.codestable/attention.md`；Glob `.codestable/` 发现 architecture / features / roadmap / brainstorms / compound / requirements，读架构总入口、看已有 feature 和 roadmap 和 brainstorm、搜 compound 看有没有相关坑（`--filter doc_type=learning`）；Grep 用户描述里的关键词防术语冲突。缺 attention.md 视为骨架不完整，不回退读外部 AI 入口 +1. **扫一眼仓库**——先读 `.codestable/attention.md`；Glob `.codestable/` 发现 features / roadmap / brainstorms / compound / requirements，读 `requirements/CONTEXT.md` 拿术语、扫 `requirements/adrs/` 看已拍板决策、看已有 feature 和 roadmap 和 brainstorm、`grep -r` 关键词 compound/ 看有没有相关坑；Grep 用户描述里的关键词防术语冲突。缺 attention.md 视为骨架不完整，不回退读外部 AI 入口 2. **是不是接续之前的工作**： - `features/` 下有名字相近的 brainstorm？`roadmap/` 下有相近子目录？`brainstorms/` 下有相关创意记录？ - 没有 → 当新讨论 @@ -134,6 +134,16 @@ case 1 / case 3 也能借这个动作（不强求落 brainstorm note），逻辑 --- +## 横切：拍板了结构性决策？ + +任何 case 下，讨论过程中只要拍板了符合 **ADR 3 判据**（难回退 + 不显然 + 真实权衡）的结构性决策——典型如选了某个库 / 模块拆分方式 / 跨模块通信模式 / 一个稳定的"我们不做 X"——提示用户： + +> 这条决策听起来该写一条 ADR（难回退 + 选了具体方案）。要不要现在走 `cs-domain` 落一条 ADR？ + +用户决定。**不在 brainstorm 里直接写 ADR**，由 cs-domain 处理。 + +--- + ## 四种 case ### case 1：已经够清楚 diff --git a/cs-decide/SKILL.md b/cs-decide/SKILL.md deleted file mode 100644 index 7702376..0000000 --- a/cs-decide/SKILL.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -name: cs-decide -description: 把已拍板的技术选型、架构决定、长期约束、编码规约记成永久性决策文档（tech-stack / architecture / constraint / convention 四种）。触发：用户说"记录决定"、"归档技术选型"、"ADR"、"记录这条约束"、"把规约写下来"，或 design / analyze 后做出重要选择。只归档已拍板的，讨论中的不归档。 ---- - -# cs-decide - -## 启动必读 - -开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 - -项目里"有意做出的选择"——技术选型 / 架构决定 / 长期约束 / 编码规约——特别容易丢失。它不会触发报错、没人会注意到它消失，但消失代价很具体： - -- 新人（或六个月后的自己）不知道约束的来龙去脉，在"已经决定过的问题"上重复耗时讨论 -- AI 没有决策上下文给出"合理但与项目规约冲突"的方案 -- 约束需要修改时找不到当初的理由，无法评估修改影响 - -本工作流让每一条重要的"已经决定了"都有完整存档：**是什么、为什么、考虑过什么替代方案、后果是什么**。 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。产物写入 `.codestable/compound/`，命名 `YYYY-MM-DD-decision-{slug}.md`，frontmatter 带 `doc_type: decision`。 - ---- - -## 四种决策类型 - -每条归属四类之一（frontmatter 的 `category` 字段标注）： - -| 类型 | 适用情境 | 示例 | -|---|---|---| -| `tech-stack` | 技术 / 库 / 框架的选型 | "用 Vite 而非 Webpack"、"状态管理用 Pinia" | -| `architecture` | 系统结构、模块划分、数据流方向 | "前后端完全分离"、"事件总线只在顶层使用" | -| `constraint` | 硬约束——某些事情**不允许**做 | "不引入 jQuery"、"所有 API 调用必须通过统一的 http 模块" | -| `convention` | 软规约——某些事情**统一这样做** | "组件命名用 PascalCase"、"副作用集中在 composables/" | - -查询时各有用途：查"用什么工具"→ tech-stack；"系统怎么组织"→ architecture；"这里为什么不能改"→ constraint；"统一做法是什么"→ convention。 - ---- - -## 文档格式 - -frontmatter / 正文模板 / 示例见同目录 `reference.md`。本技能流程约束： - -- `category` 只允许 `tech-stack` / `architecture` / `constraint` / `convention` -- `status` 只允许 `active` / `superseded` / `deprecated` -- "考虑过的替代方案"和"相关文档"是可选节，用户说"没什么"就省略 - ---- - -## 工作流阶段 - -### Phase 1：识别决策 - -用**一个问题**确认关键信息不要给用户大表格： - -1. "这个决定关于什么？（技术选型 / 架构 / 约束 / 规约）" → 确定 `category` -2. "已经拍板还是还在讨论？" → **本工作流只归档已拍板的**，讨论中的不归档（建议讨论完再来）。理由：讨论中的方案归档，下次有人查到会以为已定了，反而误导 -3. 描述不清楚问"当时为什么选这个而不选别的？" - -### Phase 1.5：查重叠与意图分流（必做） - -按 `shared-conventions.md` §6 第 5/6 条执行： - -- 用户话里含"改 / 更新 / 推翻 / 某条决策 / 某个选型"或明确指向某份旧决策 → 直接走**更新或 supersede**。决策文档特性：**结论本身变更几乎总要 supersede**（旧结论留痕不能原地覆盖）；只补背景 / 替代方案 / 影响描述时走"更新已有条目" -- 否则用下面"搜索工具"按 category + 关键词查一遍，命中相近旧决策时把候选列给用户 - -**update vs supersede**：结论变了 → supersede；结论没变只补充 → update。拿不准问用户。 - -### Phase 2：提炼要点（一次一个问题） - -用户可随时说"没什么"跳过： - -1. "当时面对的背景或问题？" -2. "决定的结论是什么？"（已说清就跳过） -3. "为什么选这个？最重要的理由？" -4. "考虑过其他方案吗？为什么没选？"（鼓励写哪怕只是直觉——后人最想知道"为什么不选 X"） -5. "这个决定对后续工作有什么影响或约束？" - -### Phase 3：起草 + 用户 review - -AI 根据对话起草完整文档（YAML frontmatter + 所有正文节）。一次性展示给用户 review，**别逐节展示逐节问**——拿到完整版才能判断节之间逻辑是否自洽。 - -### Phase 4：归档 - -- 新建：写入 `.codestable/compound/YYYY-MM-DD-decision-{slug}.md`，frontmatter 顶部带 `doc_type: decision` -- 更新：写回 Phase 1.5 定位到的原文件，frontmatter 补 `updated: YYYY-MM-DD` -- supersede：按 `shared-conventions.md` §6 第 5 条处理；旧文档 `status: superseded` + `superseded-by` - -### Phase 5：相关工作流更新提示 - -写完检查两项有则提示用户（**不自作主张改文件**）： - -1. `architecture/ARCHITECTURE.md` 的"关键架构决定"节是否应引用——`architecture` 或 `tech-stack` 通常应该 -2. `.codestable/attention.md` 是否应追加一句启动必读摘要——`constraint` 或 `convention` 通常应该 - ---- - -## 搜索工具 - -> 完整语法见 `.codestable/reference/tools.md`。 - -```bash -# 列出所有当前有效的决策 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter status=active - -# 按类型 + 状态组合 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter category=constraint --filter status=active - -# 归档后查重叠 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --query "{关键词}" --json -``` - ---- - -## 守护规则 - -> 归档类工作流共享守护规则（只增不删 / 宁缺毋滥 / 不替用户写 / 可发现性 / 归档后查重叠）见 `shared-conventions.md` 第 6 节。本技能特有： - -1. **只归档已拍板的决定**——讨论中的方案不归档 -2. **status=superseded 不等于删除**——被取代的保留原文 + `superseded-by` + 正文顶部 `**[已取代]** 见 {新文档 slug}` -3. **不替用户写理由**——用户说不出就写"未做系统评估"，不要编造（编造的理由会变成历史"事实"误导后人） -4. **不主动修改 attention.md 和 ARCHITECTURE.md**——Phase 5 只提示，由用户决定；attention.md 追加交给 `cs-note` -5. **跨技能一致性**——decision 和 attention.md 描述不同时以 decision 为详细版、attention.md 为摘要版，两者应链接不应矛盾 -6. **只认自己的 doc_type**——只读写 `doc_type: decision` diff --git a/cs-decide/reference.md b/cs-decide/reference.md deleted file mode 100644 index 5289bb3..0000000 --- a/cs-decide/reference.md +++ /dev/null @@ -1,60 +0,0 @@ -# decisions 参考模板 - -本文件提供 `cs-decide` 使用的 frontmatter、正文模板和示例。 - -## 1. frontmatter - -```yaml ---- -doc_type: decision -category: tech-stack | architecture | constraint | convention -date: YYYY-MM-DD -slug: {英文描述，连字符分隔} -status: active | superseded | deprecated -superseded-by: {可选} -area: {受影响领域} -tags: [] ---- -``` - -文件名：`.codestable/compound/YYYY-MM-DD-decision-{slug}.md`。 - -## 2. 正文模板 - -```markdown -## 背景 - -## 决定 - -## 理由 - -## 考虑过的替代方案 - -## 后果 - -## 相关文档 -``` - -`考虑过的替代方案` 和 `相关文档` 都是可选节。 - -## 3. 技术选型示例 - -```markdown ---- -doc_type: decision -category: tech-stack -date: 2026-04-11 -slug: vite-as-bundler -status: active -area: frontend -tags: [vite, bundler, build-tool] ---- - -## 背景 - -项目启动时需要选择前端构建工具。 - -## 决定 - -使用 Vite 作为开发和生产构建工具。 -``` \ No newline at end of file diff --git a/cs-libdoc/SKILL.md b/cs-doc-api/SKILL.md similarity index 76% rename from cs-libdoc/SKILL.md rename to cs-doc-api/SKILL.md index 75b4277..f178f5e 100644 --- a/cs-libdoc/SKILL.md +++ b/cs-doc-api/SKILL.md @@ -1,23 +1,23 @@ --- -name: cs-libdoc -description: 给库的公开表面（组件 / 函数 / 命令）逐条目生成参考文档，带清单追踪，支持单条目和批量。信息源是源码本身（与 guidedoc 任务导向不同）。触发：用户说"写 API 文档"、"组件文档"、"libdoc"，或 acceptance 后发现新增公开接口。 +name: cs-doc-api +description: 给库的公开表面（组件 / 函数 / 命令）逐条目生成参考文档，带清单追踪，支持单条目和批量。信息源是源码本身（与 doc-tutorial 任务导向不同）。触发：用户说"写 API 文档"、"组件文档"、"doc-api"，或 acceptance 后发现新增公开接口。 --- -# cs-libdoc +# cs-doc-api ## 启动必读 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 -guidedoc 教你"怎么用 X 做 Y"，libdoc 告诉你"X 的每个零件长什么样、怎么配"。 +doc-tutorial 教你"怎么用 X 做 Y"，doc-api 告诉你"X 的每个零件长什么样、怎么配"。 -guidedoc 写错可能是表达不清，libdoc 写错就是错——信息源是源码本身，类型 / 默认值 / 签名都有唯一正确答案。**核心规则：不靠猜、不复制改名、每个条目独立读源码**。 +doc-tutorial 写错可能是表达不清，doc-api 写错就是错——信息源是源码本身，类型 / 默认值 / 签名都有唯一正确答案。**核心规则：不靠猜、不复制改名、每个条目独立读源码**。 --- -## 和 guidedoc 的对比 +## 和 doc-tutorial 的对比 -| | guidedoc | libdoc | +| | doc-tutorial | doc-api | |---|---|---| | 性质 | 任务导向（Tutorial / How-to） | 参考导向（Reference） | | 回答 | "如何用 X 实现某个目标" | "X 的每个零件长什么样、怎么配" | @@ -25,7 +25,7 @@ guidedoc 写错可能是表达不清，libdoc 写错就是错——信息源是 | 信息源 | 方案 doc + 用户知识 | **源码本身**（类型 / 注释 / 默认值） | | 数量级 | 几篇到十几篇 | 几十到上百篇 | -互补：guide 引用 libdoc 做详细参考（"完整 props 见 xxx"），libdoc 的"相关条目"链回 guide。 +互补：doc-tutorial 引用 doc-api 做详细参考（"完整 props 见 xxx"），doc-api 的"相关条目"链回 doc-tutorial。 ## "条目（entry）" @@ -42,7 +42,7 @@ guidedoc 写错可能是表达不清，libdoc 写错就是错——信息源是 ## 涉及路径 -libdoc 产物**不在 `.codestable/` 下**——API 参考是面向外部读者的可发布产物。 +doc-api 产物**不在 `.codestable/` 下**——API 参考是面向外部读者的可发布产物。 - 条目文档 → `docs/api/{slug}.md` - 条目清单 → `docs/api/manifest.yaml` @@ -59,7 +59,7 @@ libdoc 产物**不在 `.codestable/` 下**——API 参考是面向外部读者 - 条目文档 frontmatter 和正文模板 - 源码提取清单（接口签名、默认值、导出方式等） -本技能正文只保留流程约束：**libdoc 以源码为事实源，不靠猜，不复制上一个条目改名**。 +本技能正文只保留流程约束：**doc-api 以源码为事实源，不靠猜，不复制上一个条目改名**。 --- @@ -112,11 +112,10 @@ libdoc 产物**不在 `.codestable/` 下**——API 参考是面向外部读者 | 来源 | 关系 | |---|---| -| `cs-feat-accept` | 验收后新增/修改库公开接口 → 推送"需要更新 libdoc 吗？" | -| `cs-guide` | guide 引用 libdoc 做详细参考；libdoc "相关条目"链回 guide | -| `cs-arch` (check) | 检测到接口变更但 libdoc 未同步时把对应条目标 `outdated`，本技能 Phase 3 处理 | -| `cs-feat-design` | 方案第 2 节可作 libdoc 补充信息源（**但以源码为准**） | -| `cs-trick` | libdoc "注意事项"与 tricks 重合时交叉引用而不重复写 | +| `cs-feat-accept` | 验收后新增/修改库公开接口 → 推送"需要更新 doc-api 吗？" | +| `cs-doc-tutorial` | doc-tutorial 引用 doc-api 做详细参考；doc-api "相关条目"链回 doc-tutorial | +| `cs-feat-design` | 方案第 2 节可作 doc-api 补充信息源（**但以源码为准**） | +| `cs-keep` | doc-api "注意事项"与 compound 沉淀重合时交叉引用而不重复写 | --- @@ -135,10 +134,10 @@ libdoc 产物**不在 `.codestable/` 下**——API 参考是面向外部读者 ## 容易踩的坑 - 没扫清单就写文档——可能遗漏或重复 -- 没读源码就写 API 参考——libdoc 核心价值是准确反映源码 +- 没读源码就写 API 参考——doc-api 核心价值是准确反映源码 - 复制上一个条目改名——必然漏掉微妙差异 - 批量模式跳过样板确认——50 篇全白写 -- 把 spec 信息（不变量 / 测试约束）写进 libdoc——属于 `.codestable/` -- libdoc 和 guidedoc 内容高度重叠——其中一份定位有误 +- 把 spec 信息（不变量 / 测试约束）写进 doc-api——属于 `.codestable/` +- doc-api 和 doc-tutorial 内容高度重叠——其中一份定位有误 - `manifest.yaml` 直接删行——改 `status: skipped` 并写 note - 源码接口不存在却在文档写了——以源码为事实源不编造 diff --git a/cs-libdoc/reference.md b/cs-doc-api/reference.md similarity index 87% rename from cs-libdoc/reference.md rename to cs-doc-api/reference.md index 4d46594..89945e1 100644 --- a/cs-libdoc/reference.md +++ b/cs-doc-api/reference.md @@ -1,6 +1,6 @@ -# libdoc 参考模板 +# doc-api 参考模板 -本文件提供 `cs-libdoc` 使用的 manifest、条目文档模板和源码提取清单。 +本文件提供 `cs-doc-api` 使用的 manifest、条目文档模板和源码提取清单。 ## 1. `manifest.yaml` 格式 diff --git a/cs-guide/SKILL.md b/cs-doc-tutorial/SKILL.md similarity index 84% rename from cs-guide/SKILL.md rename to cs-doc-tutorial/SKILL.md index 26f6a35..6efdc5e 100644 --- a/cs-guide/SKILL.md +++ b/cs-doc-tutorial/SKILL.md @@ -1,15 +1,15 @@ --- -name: cs-guide -description: 写或更新对外指南文档——开发者指南（dev-guide）和用户指南（user-guide），产物在项目 docs/ 目录。任务导向（怎么用 X 做 Y），与 libdoc 的零件参考不同。触发：用户说"写文档"、"开发者指南"、"用户指南"，或 feature-acceptance 收尾时推送。 +name: cs-doc-tutorial +description: 写或更新对外指南文档——开发者指南（dev-guide）和用户指南（user-guide），产物在项目 docs/ 目录。任务导向（怎么用 X 做 Y），与 doc-api 的零件参考不同。触发：用户说"写文档"、"开发者指南"、"用户指南"，或 feature-acceptance 收尾时推送。 --- -# cs-guide +# cs-doc-tutorial ## 启动必读 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 -代码解决问题，文档让别人能用它解决问题。spec 记录"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要面向自己角色的、可发布的指南。guidedoc 就是从 spec 和代码出发写成读者真正能用的指南。 +代码解决问题，文档让别人能用它解决问题。spec 记录"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要面向自己角色的、可发布的指南。doc-tutorial 就是从 spec 和代码出发写成读者真正能用的指南。 --- @@ -31,7 +31,7 @@ description: 写或更新对外指南文档——开发者指南（dev-guide） | 情境 | 说明 | |---|---| | feature-acceptance 结束 | 主动推：方案第 2 节（接口契约）有变更问"需要更新 dev-guide 吗？"；第 1 节（用户可见行为）有变更问"需要更新 user-guide 吗？" | -| 用户主动触发 | "写文档"、"guidedoc"、"补一份开发者指南" | +| 用户主动触发 | "写文档"、"doc-tutorial"、"补一份开发者指南" | | onboard 完成后 | 新仓库可触发补全基础文档骨架 | 主动推送一句话即可，用户说"不用"就别再提——多次推会让用户觉得 AI 在加戏。 @@ -40,7 +40,7 @@ description: 写或更新对外指南文档——开发者指南（dev-guide） ## 涉及路径 -guidedoc 产物**不在 `.codestable/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。 +doc-tutorial 产物**不在 `.codestable/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。 - dev-guide → `docs/dev/{slug}.md` - user-guide → `docs/user/{slug}.md` @@ -101,7 +101,7 @@ last_reviewed: YYYY-MM-DD （可选）边界、性能考虑、已知 bug 绕过方式。 ## 相关文档 -关联的 user-guide、方案 doc、架构 doc 或外部参考。 +关联的 user-guide、方案 doc、相关 ADR 或外部参考。 ``` ### user-guide 正文结构 @@ -143,10 +143,8 @@ A: ... | `cs-feat-accept` | 验收后主动推：接口变更推 dev-guide，用户可见变更推 user-guide | | `cs-feat-design` | 方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源 | | `cs-onboard` | 新仓库接入后可补全基础文档骨架 | -| `cs-arch` (check) | 检测到 design 与代码不一致时对应 guide 应同步标 `outdated` | -| `cs-decide` | dev-guide 引用的技术选型应来自 decisions，不独立发明 | -| `cs-trick` | dev-guide 用法示例若与 tricks 重合，交叉引用而不重复写 | -| `cs-libdoc` | guide 引用 libdoc 条目做详细参考；libdoc 是零件参考，guidedoc 是任务教程 | +| `cs-keep` | dev-guide 引用的技术选型 / 用法示例若 compound 里已有沉淀，交叉引用而不重复写 | +| `cs-doc-api` | guide 引用 doc-api 条目做详细参考；doc-api 是零件参考，doc-tutorial 是任务教程 | --- diff --git a/cs-domain/SKILL.md b/cs-domain/SKILL.md new file mode 100644 index 0000000..f884255 --- /dev/null +++ b/cs-domain/SKILL.md @@ -0,0 +1,143 @@ +--- +name: cs-domain +description: 维护项目的领域模型（domain model）——CONTEXT.md 术语表 + ADR 决策记录 + 单/多 context 拓扑。触发：用户说"记一条决策"/"拍板了"/"加个术语"/"这个项目要分子系统了"，或 cs-brainstorm / cs-feat-design / cs-refactor 拍板时路由过来。 +--- + +# cs-domain + +先读 `.codestable/attention.md`；缺失提示跑 `cs-onboard`。 + +cs-domain 管三件事：**术语**（CONTEXT.md）、**决策**（ADR）、**拓扑**（单 context ↔ 多 context）。所有产物在 `.codestable/requirements/` 下。 + +## 拓扑判断 + +每次启动先扫一眼，确定项目当前处于哪种拓扑： + +- `.codestable/requirements/CONTEXT-MAP.md` 存在 → **多 context** 模式 +- 只有 `.codestable/requirements/CONTEXT.md` → **单 context** +- 都没有 → 项目还没起 domain 文档，按需 lazy 创建 + +## 单 context 路径 + +``` +.codestable/requirements/ +├── CONTEXT.md # 术语表 +├── adrs/ # 顺序编号 ADR +│ ├── 001-xxx.md +│ └── 002-xxx.md +└── {capability}.md # 能力 doc（cs-req 产出，不归本技能管） +``` + +## 多 context 路径 + +``` +.codestable/requirements/ +├── CONTEXT-MAP.md # 子 context 列表 + 关系 +├── adrs/ # 系统级 ADR（跨 context） +├── ordering/ +│ ├── CONTEXT.md # 子 context 术语 +│ └── adrs/ # 子 context 特定 ADR +└── billing/ + ├── CONTEXT.md + └── adrs/ +``` + +## CONTEXT.md 写作规范 + +CONTEXT.md 是**术语表，不是 spec**。只写"X 是什么"，不写"X 怎么实现"。 + +格式： + +```md +# {Context 名} + +{一两句描述这个 context 是什么、为什么存在。} + +## Language + +**Order**: +{一两句话定义。} +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request +``` + +规则： + +- **下定义，不描述行为**——写 "X 是什么"，不写 "X 做什么" +- **同义词列在 `_Avoid_`**——多个词指同一概念时挑最好的，其他列为禁用 +- **只收项目特有术语**——通用编程概念（timeout、error type）不进 +- **聚类用子标题**——同领域术语自然分组就给小节 + +## ADR 写作 + +### 何时该写（守门 3 判据，必须同时满足） + +1. **难以回退**——以后改主意成本明显 +2. **不带上下文就难理解**——读者会问"为什么这么做" +3. **真实权衡的结果**——有备选方案，因为具体原因挑了一个 + +三条少一条就**不写**。轻易能回退的决定不写、不奇怪的决定不写、没真备选的决定不写。 + +### 路径与编号 + +- 单 context：`.codestable/requirements/adrs/NNN-{slug}.md` +- 多 context 子系统 ADR：`.codestable/requirements/{ctx}/adrs/NNN-{slug}.md` +- 多 context 系统级 ADR（跨 context）：`.codestable/requirements/adrs/NNN-{slug}.md` +- 编号 3 位（001、002...）；扫对应 adrs/ 目录最大编号 + 1 +- `{slug}` kebab-case，能让人一眼想起决策内容 + +### Frontmatter + +```yaml +--- +id: 001 +title: 选择 X 而不是 Y +status: proposed | accepted | superseded | deprecated | partially-superseded +date: YYYY-MM-DD +supersedes: [003] # 可选 +superseded_by: [015, 017] # 可选 +relates_to: [requirements/{slug}, 002] # 可选 +--- +``` + +### 正文（Nygard 四节） + +```md +# {Title} + +## Context +{决策面对的问题、约束、当时的状况。} + +## Decision +{我们决定做什么。} + +## Consequences +{这个决定带来的正负影响、新出现的约束。} + +## Alternatives Considered +{讨论过的备选方案 + 为什么没选。} +``` + +写 ADR 时用 CONTEXT.md 里已定义的术语；用到新术语就顺手 `_Avoid_` 别名补到 CONTEXT.md。 + +## 单 → 多 context 升级 + +**显式触发**——用户必须明确说"这项目要分子系统了"才升级。不要因为 CONTEXT.md 长就自动建议。 + +升级流程： + +1. 跟用户对齐子 context 列表（典型 2-4 个，超过 5 个先质疑是不是切得太细） +2. 创建 `CONTEXT-MAP.md`：列子 context + 它们之间的关系（事件流、共享类型、调用方向） +3. 为每个子 context 建子目录 + `CONTEXT.md` + `adrs/` +4. 把原 `CONTEXT.md` 的术语按归属拆到各子 context；跨多个 context 的术语留在 `CONTEXT-MAP.md` 顶层 Language 节 +5. 把原 `adrs/` 下的 ADR 按影响范围分：跨 context 的留原位（系统级），单 context 内部的 mv 到对应 `{ctx}/adrs/` +6. 不动 `{capability}.md`——能力 doc 归 cs-req 管，升级时 cs-req 跟进归类（cs-domain 不替它做） + +## 退出条件 + +- 写 ADR：文件落盘 + 编号正确 + frontmatter 完整 + Nygard 四节齐 +- 写 CONTEXT：术语进对位置（单/多 context 拓扑判断正确）+ 同义词列到 `_Avoid_` +- 升级拓扑：CONTEXT-MAP.md + 子目录创建完 + 术语拆分完 + ADR 分级完 diff --git a/cs-explore/SKILL.md b/cs-explore/SKILL.md deleted file mode 100644 index ed7fa67..0000000 --- a/cs-explore/SKILL.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -name: cs-explore -description: 对仓库做定向代码探索并把"提问→读代码→得结论"沉淀为可检索证据，三种类型 question / module-overview / spike。触发：用户说"先 explore 一下"、"这个仓库里 X 怎么实现"、"快速熟悉这个模块"、"把探索结果存档"。 ---- - -# cs-explore - -## 启动必读 - -开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 - -同一个问题第一次花两小时查代码，第二次应该五分钟内找到答案——前提是第一次做完留下证据化的记录。cs-explore 把"提问 → 读代码 → 得结论"沉淀成可检索的探索文档。 - ---- - -## 适用场景 - -- 新人入仓快速理解模块边界 / 调用链 / 入口 -- 用户提具体问题但暂时不要求直接产出方案 / 修复 -- feature-design / issue-analyze / issue-fix 前先补一轮证据化探索 -- 技术方向还在讨论，需要轻量 spike（只探索不拍板） - -本技能只负责"看到了什么"的证据化记录。用户意图是别的（拍板 / 处方 / 修 bug）让用户按场景选对应子技能。 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。产物写入 `.codestable/compound/`，命名 `YYYY-MM-DD-explore-{slug}.md`，frontmatter 带 `doc_type: explore`。 - ---- - -## 三种探索类型 - -frontmatter 的 `type` 字段： - -| 类型 | 适用情境 | -|---|---| -| `question` | 围绕一个具体问题查代码并给结论 | -| `module-overview` | 快速梳理某模块结构 / 边界 / 入口 / 依赖 | -| `spike` | 对多个可能方向做轻量技术探查（不做最终决策） | - ---- - -## 文档格式 - -frontmatter / 正文结构 / 各节写法说明和示例见同目录 `reference.md`。流程约束： - -- **速答必须先于证据出现**——读者打开先看到结论再决定要不要往下看证据 -- 结论必须可回溯到证据，不允许纯猜测 -- 证据不足时 `confidence` 必须降为 `medium` 或 `low` -- 旧探索过期：旧文档标 `outdated`，新增当前版本 - ---- - -## 工作流阶段 - -### Phase 1：收敛探索问题 - -最多两个问题： - -1. "你最想先回答的一个问题是什么？" -2. "希望聚焦哪个模块 / 目录？" - -用户描述已清楚直接进 Phase 1.5。 - -### Phase 1.5：查重叠与意图分流（必做） - -按 `shared-conventions.md` §6 第 5/6 条执行： - -- 含"更新 / 复查 / 某次 explore / 这个模块之前探过"或指向某份旧 explore → 走**更新或 supersede**。explore 特性：**代码已变导致旧结论失效**时旧文档 `status: outdated` + 新建一份（supersede）；只补证据 / 收紧结论但核心结论未变时走"更新已有" -- 否则用搜索工具按关键词 / 模块查一遍，命中相近旧 explore 时先读它，能直接回答就告诉用户"已有一份在 {路径}，复用还是重探一遍？" - -**更新路径**：读旧文档 → 按 Phase 2 补证据 → 改写速答节 → 写回原文件 + `updated: YYYY-MM-DD`。 - -### Phase 2：证据化探索 - -- 用 Glob / Grep / Read **真实读代码**不靠猜 -- 边读边积累证据；**同步思考每条证据支撑哪个结论**——不支撑任何结论的证据不记录 -- 关键证据 3-8 条，每条都标注 `文件:行号` -- 多模块协作或 `module-overview` / `spike` 类型 → 准备一张 Mermaid 图放在速答节里 -- 形成初步结论后主动检查：已有证据能否说服持怀疑态度的人？够了就停不必扩大搜索 - -为什么"够了就停"：探索不是穷举，是建立到"读者能信"为止的证据链。继续扩大只会让文档变长而不变可信。 - -### Phase 3：起草与确认 - -- **先写速答节，再回填关键证据**——这个顺序很重要：先有结论再回头看证据是否真支持，能逼你检查每条证据的实际效力 -- AI 一次性起草完整文档，用户 review 后确认 -- 有修改按反馈修订后再落盘 - -### Phase 4：归档 - -- 新建：写入 `.codestable/compound/YYYY-MM-DD-explore-{slug}.md`，frontmatter 带 `doc_type: explore` -- 更新：写回 Phase 1.5 定位的原文件 + `updated: YYYY-MM-DD` -- supersede：按 `shared-conventions.md` §6 第 5 条；旧文档 `status: outdated` + `superseded-by` - -### Phase 5：给出下一步建议 - -证据收齐后一句话提示下一步方向（"要不要基于这份 explore 去设计方案"）。用户说"不用"就跳过——下一步由用户自己决定。 - ---- - -## 搜索工具 - -> 完整语法见 `.codestable/reference/tools.md`。 - -```bash -# 按类型筛选 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --filter type=module-overview --filter status=active - -# 归档后查重叠 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --query "{关键词}" --json -``` - ---- - -## 退出条件 - -- [ ] 已明确探索问题与范围 -- [ ] 速答节给出核心结论（结论前置） -- [ ] 关键证据 3-8 条，每条标 file:line 并说明支撑哪个结论 -- [ ] 多模块或 module-overview / spike 类型时速答节有 Mermaid 图 -- [ ] 文档已归档到 `compound/` -- [ ] 已给出后续建议 - ---- - -## 守护规则 - -> 归档类共享规则见 `shared-conventions.md` 第 6 节。本技能特有反模式： - -- 不读代码直接给结论 -- 证据只写"看起来像"不写 file:line -- 结论写在证据之后——速答节必须在关键证据节之前 -- 证据节比速答节长数倍——精简证据，不支撑结论的删掉 -- 跨模块流程没 Mermaid 图，只靠文字描述 -- 提前拍板——explore 只记"看到了什么"不下"以后应该怎么做" -- 直接给处方没证据链——每条结论必须回溯到 file:line -- 历史 explore 已过期却继续引用，不做 `status` 标注 -- 读写非 `doc_type=explore` 的文档——本技能只负责 explore diff --git a/cs-explore/reference.md b/cs-explore/reference.md deleted file mode 100644 index 547e8df..0000000 --- a/cs-explore/reference.md +++ /dev/null @@ -1,44 +0,0 @@ -# explore 参考模板 - -本文件提供 `cs-explore` 使用的 frontmatter、正文结构和写作说明。 - -## 1. frontmatter - -```yaml ---- -doc_type: explore -type: question | module-overview | spike -date: YYYY-MM-DD -slug: {英文描述，连字符分隔} -topic: {一句话描述探索问题} -scope: {探索范围} -keywords: [] -status: active | outdated -confidence: high | medium | low ---- -``` - -文件名：`.codestable/compound/YYYY-MM-DD-explore-{slug}.md`。 - -## 2. 正文结构 - -```markdown -## 问题与范围 -## 速答 -## 关键证据 -## 细节展开 -## 未决问题 -## 后续建议 -## 相关文档 -``` - -## 3. 写法说明 - -- `速答` 必须结论前置 -- `关键证据` 目标 3–8 条 -- 涉及多模块协作时，在速答节附 Mermaid 图 -- 结论必须能被证据支撑 - -## 4. 后续建议 - -`后续建议` 节写一句话提示用户接下来可能的方向（下一步由用户自己决定，本节不枚举候选技能）。用户说"不用"就跳过。 \ No newline at end of file diff --git a/cs-feat-accept/SKILL.md b/cs-feat-accept/SKILL.md index 357300f..b1f4641 100644 --- a/cs-feat-accept/SKILL.md +++ b/cs-feat-accept/SKILL.md @@ -1,6 +1,6 @@ --- name: cs-feat-accept -description: feature 流程阶段 3——验收闭环：对照 design 核实现 + review 报告 + QA 报告或验收现场验证证据 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 cs-feat-impl 完成、cs-code-review 通过；如果未单独执行 cs-feat-qa，accept 必须现场补齐同等验证证据。 +description: feature 流程阶段 3——验收闭环：对照 design 核实现 + review 报告 + QA 报告或验收现场验证证据 + 盘点 cs-domain 候选（提示而非代写）+ 回写 requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 cs-feat-impl 完成、cs-code-review 通过；如果未单独执行 cs-feat-qa，accept 必须现场补齐同等验证证据。 --- # cs-feat-accept @@ -12,11 +12,11 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现 代码已经写完，但流程没结束。本阶段做四件事，缺一不可： 1. **核对实现有没有偏离方案**——逐层对照 `{slug}-design.md`，发现偏差当场修，**不是在报告里"记一下"**就过去 -2. **把 feature 归并到整体架构**——对照方案第 4 节，实际去更新架构中心目录下的相关 doc +2. **盘点领域影响**——识别本次是否引入新术语 / 结构性决策，提示用户走 `cs-domain` 写 CONTEXT.md / ADR（不在 accept 里代写） 3. **能力落档到 requirement**——draft req 对应的能力实现完成后升级为 current（保留愿景，追加变更日志）；从未写过 req 的能力 backfill 4. **完成状态回写到 roadmap**——方案 frontmatter 有 `roadmap` / `roadmap_item` 字段时**必须**改 items.yaml 对应条目为 `done` 并同步主文档 -漏掉任何一件的代价：架构 doc 过期下个 feature 读到错信息；req 和实际能力脱节；roadmap 规划层和实际进度脱节，下次推进会重复跑流程。 +漏掉任何一件的代价：CONTEXT.md / adrs/ 没跟上下个 feature 读到错术语；req 和实际能力脱节；roadmap 规划层和实际进度脱节，下次推进会重复跑流程。 **验收原则**：acceptance 是最终审计，不是实现汇报的整理。要重新读取原始 design 和 checklist，以最终工作区为准逐项复验；实现阶段说通过只能当线索，不能当结论。发现缺口要先修代码 / 方案 / 文档并重验，再写通过。 @@ -40,7 +40,7 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现 - 第 1 节：决策与约束（需求摘要 / 复杂度档位 / 关键决策 / 前置依赖） - 第 2 节：名词与编排（2.1 名词层 / 2.2 编排层 / 2.3 挂载点 / 2.4 推进策略） - 第 3 节：验收契约（关键场景清单 + 反向核对项） -- 第 4 节：与项目级架构文档的关系 +- 第 4 节：领域影响（新术语 / 结构性决策 / 流程级约束） **Fastforward design**：第 0 需求摘要 / 第 1 设计方案 / 第 2 验收标准 / 第 3 推进步骤 @@ -59,7 +59,7 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现 6. **核心证据复核**——不管证据来自 QA 报告还是 accept-inline，都按同一标准复核： - 功能性或 mixed feature：design 第 3 节、checklist checks、review QA focus 中的核心功能路径必须有运行证据。若核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行，acceptance 必须写 `status=blocked`。下一步按原因选择：代码/测试缺口 → `cs-feat-impl` qa-fix 后重跑 review 和 accept-inline；环境缺口 → 先补环境；用户希望独立 QA 报告 → 跑 `cs-feat-qa`。 - 非功能性 feature：不要求 e2e / browser / API，但必须写明为什么不需要端到端运行，并提供静态检查、diff 复核、文档一致性、schema/快照/类型/构建/目标测试等替代证据。缺说明或证据不足时继续补证据，不直接通过。 -7. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 流程级约束、2.3 挂载点、第 3 节场景）+ checklist + review 报告（findings / residual risk / Test And QA Focus）+ QA 报告（如有：Feature type / Core evidence gate / Verification Matrix / Command Results / Scenario Results / residual-risk）+ accept-inline 验证矩阵（如无 QA 报告）+ implement 完成汇报里的基线预检 / step 证据 / 实际交付物索引 / 知识回写候选 + 第 4 节提到的所有架构 doc + 本次代码改动（git log / diff） +7. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 流程级约束、2.3 挂载点、第 3 节场景）+ checklist + review 报告（findings / residual risk / Test And QA Focus）+ QA 报告（如有：Feature type / Core evidence gate / Verification Matrix / Command Results / Scenario Results / residual-risk）+ accept-inline 验证矩阵（如无 QA 报告）+ implement 完成汇报里的基线预检 / step 证据 / 实际交付物索引 / 知识回写候选 + 第 4 节提到的领域影响候选 + `requirements/CONTEXT.md` + 相关 ADR + 本次代码改动（git log / diff） 8. **断点恢复**——`{slug}-acceptance.md` 已存在且部分填好 → 从下一个未完成节继续，跳过 checks 中已 `passed` 的项；汇报"上次做到第 X 节，从第 Y 节继续" **Fastforward design 验收报告映射表**： @@ -70,7 +70,7 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现 | 2 行为与决策核对（含挂载点） | 第 1 节 + 第 2.2 + 第 2.3 | 第 0 节；挂载点现场盘点 | | 3 验收场景核对 | 第 3 节场景清单 + 反向核对 | 第 2 节验收标准 | | 4 术语一致性 | 第 0 节 + 第 2.1 命名 | 检查代码命名一致性 | -| 5 架构归并 | 第 4 节 | 通常无；写"无架构维度变更" | +| 5 领域影响盘点 | 第 4 节 | 通常无；写"无领域维度变更" | --- @@ -165,25 +165,20 @@ Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中 发现不一致 → 改代码，别在报告里写"已知差异"。 -## 5. 架构归并 +## 5. 领域影响盘点（提示而非代写） -**目标**：把本次 feature 里稳定、系统级可见的内容**实际写入** architecture，让读者只看 architecture 就能看懂新能力的存在和形态。**不是加 design 链接就算数**。 +**目标**：识别本次 feature 是否引入了应进 CONTEXT.md / adrs/ 的内容，**提示用户走 cs-domain**——不在 accept 里替它写。 -对照方案第 4 节，三类东西实际写入对应架构 doc： +对照方案第 4 节 + 实际实现，三类信号逐项盘点： -- **名词归并** ← 第 2.1 节新增 / 变化的实体、类型、对外契约 → architecture 的"结构与交互 / 数据与状态"节 -- **动词骨架归并** ← 第 2.2 节跨模块可见的主流程 / 关键编排 → architecture 的结构图 / 模块交互 -- **流程级约束归并** ← 第 2.2 节跨 feature 稳定的约束 → architecture 的"已知约束"节 +- **新名词** → `requirements/CONTEXT.md` 候选：新增 / 改名的实体、类型、对外契约；grep CONTEXT.md 看是否已有定义，没有就提示"走 cs-domain 加术语？" +- **结构性选择**（满足 ADR 3 判据：难回退 + 不显然 + 真权衡）→ `requirements/adrs/` 候选：新增模块 / 跨模块接口模式 / 新依赖选型 / 拒绝的备选 +- **流程级约束** → `requirements/adrs/` 候选：稳定的错误语义 / 幂等约束 / 扩展点规约 逐项核对： -- [ ] 架构 doc X（{路径}）：归并内容 {描述}；已写入 ✓ / 不需要（理由：{具体}） +- [ ] 候选 X（{术语 / 结构选择 / 流程约束}）：建议 {cs-domain 写 CONTEXT / 写 ADR} → 已建议用户 ✓ / 不需要（理由：{具体}） -方案第 4 节为空或过简 → 在此补充评估： -- 新增哪些模块 / 改了哪些接口 / 引入哪些跨模块纪律 -- 架构总入口要不要新增描述（描述不是贴链接） -- `.codestable/attention.md` 要不要补新规约或已知坑 - -**判据**：归并完成后，没读过 design 的人打开 architecture 应该能知道"系统里现在有这个能力、它的大致形态、和它交互要遵守什么"。 +**不在 accept 里直接改 CONTEXT.md 或写 ADR**——这是 cs-domain 的事。accept 只盘点 + 建议。本节是登记表，不是动作。 ## 6. requirement delta / clarification 回写 @@ -207,7 +202,7 @@ req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement** - 同步 `{roadmap}-roadmap.md` 主文档第 3 节子 feature 清单的对应条目状态 - [ ] 两字段不一致（只填了一个）→ 停下来补齐或澄清 -衔接协议看 `shared-conventions.md` 第 2.5 节。和归并 / req 同规则：实际写文件的动作。 +衔接协议看 `shared-conventions.md` 第 2.5 节。和 req 同规则：实际写文件的动作。 ## 8. attention.md 候选盘点 @@ -259,7 +254,7 @@ req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement** - [ ] 第 1/2 节核对全部勾选，无未处理偏差（含挂载点 grep + 拔除沙盘推演） - [ ] 第 3 节场景核对全部勾选；功能性前端已浏览器验证，非功能性前端已有替代证据 - [ ] 第 4 节术语一致性无遗漏 -- [ ] 第 5 节归并：每条有明确结论，需要更新的 doc 已实际写入 +- [ ] 第 5 节领域影响盘点：每条候选有明确结论（已建议 cs-domain / 不需要） - [ ] 第 6 节 req 回写有结论：跳过 / 未变 / 已 backfill / draft→current / 已 update - [ ] 第 7 节 roadmap 回写有结论：跳过（非 roadmap 起头）/ 已更新（items.yaml + 主文档同步，yaml 通过校验） - [ ] checklist 所有 checks 都 `passed` @@ -270,23 +265,22 @@ req 是能力愿景层，但 **accept 阶段不自由重写长期 requirement** ## 退出后 -告诉用户："验收报告已就绪，架构文档已归并，cs-feat 工作流走完。后续 BUG 走 issue 流程。" +告诉用户："验收报告已就绪，领域影响候选已盘点，cs-feat 工作流走完。后续 BUG 走 issue 流程。" 按 `shared-conventions.md` 第 3 节收尾推荐顺序逐项一句话提示（用户说"不用"立刻跳过）： -1. 复用价值的坑点 / 经验 → "需要沉淀 learning 吗？（`cs-learn`）" -2. 长期约束 / 技术选型 → "需要归档决定吗？（`cs-decide`）" - - **特检**：design 第 2.5 节是否有"建议沉淀的 convention"段。有就把那条规则原文念给用户："design 2.5 建议沉淀这条 convention：『{规则一句话}』，跑通了，要不要现在 `cs-decide` 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提 -3. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-guide`）" -4. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-libdoc`）" -5. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条** -6. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）" -7. 最后问是否代为 scoped-commit +1. 复用价值的坑点 / 经验 / 长期约束 / 技术选型 → "沉淀到 compound？（`cs-keep`）" + - **特检**：design 第 2.5 节是否有"建议沉淀的 convention"段。有就把那条规则原文念给用户："design 2.5 建议沉淀这条 convention：『{规则一句话}』，跑通了，要不要现在 `cs-keep` 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提 +2. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-doc-tutorial`）" +3. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-doc-api`）" +4. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条** +5. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）" +6. 最后问是否代为 scoped-commit -收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的架构 doc / req doc / roadmap items.yaml + 主文档。 +收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的 req doc / CONTEXT.md / ADR / roadmap items.yaml + 主文档。 --- ## 容易踩的坑 -常见坑（测试/QA passed ≠ 验收场景满足、挂载点要 grep 不能只看清单、归并是当下动作不是建议、final audit 缺口要先修不能写"遗留"、accept 不自由重写 requirement 必须走 delta、未经用户终审 / 同意不宣告完成或 commit 等）见同包 `reference.md`。 +常见坑（测试/QA passed ≠ 验收场景满足、挂载点要 grep 不能只看清单、领域盘点是当下动作不是建议、accept 不直接改 CONTEXT.md 或写 ADR——那是 cs-domain 的事，accept 只盘点 + 建议、final audit 缺口要先修不能写"遗留"、accept 不自由重写 requirement 必须走 delta、未经用户终审 / 同意不宣告完成或 commit 等）见同包 `reference.md`。 diff --git a/cs-feat-design/SKILL.md b/cs-feat-design/SKILL.md index 048ac86..1395bdd 100644 --- a/cs-feat-design/SKILL.md +++ b/cs-feat-design/SKILL.md @@ -150,9 +150,10 @@ design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在 - design 部分节缺失 → 补缺失节，汇报"上次写到 X，补齐统一给你 review" - design `status=approved` → 别默认覆盖，问用户接着改还是另起 slug 2. **扫 .codestable/ 全局输入**——Glob `.codestable/` 发现可用目录和文档类型，按类取用： - - `architecture/` → 读 ARCHITECTURE.md + 索引 + 相关子系统 doc，关注名词复用和流程级约束 - - `requirements/` → 有对应 req：frontmatter `requirement` 填 slug，读"用户故事 / 边界"两节；新能力首次出现 → 触发 `cs-req draft` 起草愿景 req，frontmatter `requirement` 填新 slug；纯重构 / 技术债留空 - - `compound/` → 用 `search-yaml.py --dir .codestable/compound` 搜相关 decision / explore / trick / learning；命中冲突 decision 必须正面回应 + - `requirements/CONTEXT.md` → 读领域术语表，用项目术语命名，不自己造名 + - `requirements/adrs/` → 跨模块或流程级约束相关的 ADR 必读；命中和方案冲突的 ADR **必须**正面回应"为什么仍然这么做"或调整方案 + - `requirements/{slug}.md` → 有对应 req：frontmatter `requirement` 填 slug，读"用户故事 / 边界"两节；新能力首次出现 → 触发 `cs-req draft` 起草愿景 req，frontmatter `requirement` 填新 slug；纯重构 / 技术债留空 + - `compound/` → `grep -r "关键词" .codestable/compound/` 搜历史沉淀；命中相关坑点 / 写法约束就融进方案 - `features/` → 搜历史 design 有无同类 feature 可参考 - 其余目录按内容类型自行判断 3. **读需求相关的现有代码**——读哪些文件由需求线索决定 @@ -177,7 +178,7 @@ design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在 代价：放错了模块就变"什么都装的筐"；新建平行实现就有几个版本同存。 -结论写进第 1 节"决策与约束"。涉及新建模块或跨模块接口时同步写进第 4 节，提示在 `ARCHITECTURE.md` 加指向。 +结论写进第 1 节"决策与约束"。涉及新建模块或跨模块接口时，提示用户走 `cs-domain` 起一条 ADR 记下这个结构性决策。 AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 @@ -195,7 +196,7 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 3. **做微重构（重组目录）**——目标目录摊平且能通过纯文件移动 + import 路径更新解决（编译器全程绿灯） 选择 2 / 3 时给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为**第 1 步且独立验证退出**，再开始 feature 主体 -- **重组目录时多问一步：是稳定模式还是一次性整理**——稳定模式（如"自定义业务组件统一放 `components/custom/`"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 `cs-decide` 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。**design 阶段不直接归档**——方案还没真跑过，留钩子给 implement 后再决定 +- **重组目录时多问一步：是稳定模式还是一次性整理**——稳定模式（如"自定义业务组件统一放 `components/custom/`"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 `cs-keep` 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。**design 阶段不直接归档**——方案还没真跑过，留钩子给 implement 后再决定 - **design 只做安全的微重构，边界严格守住**："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定 - **第 2.5 节随整稿一起 review，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长 diff --git a/cs-feat-design/reference.md b/cs-feat-design/reference.md index 59c1ce4..1f963d8 100644 --- a/cs-feat-design/reference.md +++ b/cs-feat-design/reference.md @@ -155,9 +155,7 @@ design 的灵魂。**所有子节用"现状 → 变化"两段式**——不写" **评估前先查 compound**——围绕"目录组织 / 文件归属 / 命名约定"关键词查一次： ```bash -python .codestable/tools/search-yaml.py --dir .codestable/compound \ - --filter doc_type=decision --filter category=convention \ - --query "目录组织 OR 命名 OR 归属" +grep -rE "目录|命名|归属|composable|组件" .codestable/compound/ ``` 命中已有 convention（如"composable 统一放 `src/composables/`"）：本节相关维度结论直接写"按 compound `{slug}` 执行"，不再讨论。 @@ -191,7 +189,7 @@ python .codestable/tools/search-yaml.py --dir .codestable/compound \ - 是否稳定模式：{一次性整理 → 省略整段；稳定模式 → 继续填以下} - 规则一句话：{如"自定义业务组件统一放 src/components/custom/，通用组件放 src/components/common/"} - 适用范围：{本仓库全部 / 仅 frontend / 仅某模块} - → 建议 implement 跑通后走 `cs-decide` 归档为 `category: convention`，未来 design 在开篇 compound 检索就能命中 + → 建议 implement 跑通后走 `cs-keep` 归档到 compound/，未来 design 在开篇 compound 检索就能命中 ##### 超出范围的观察（可选，仅提示不阻塞） - {文件路径 / 目录路径}：{发现的结构性问题——职责重划 / 模块拆合 / 接口语义需要变 / 跨文件依赖混乱} @@ -202,7 +200,7 @@ python .codestable/tools/search-yaml.py --dir .codestable/compound \ - 选"微重构"必须满足"只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，**不要在 design 里做也不要作为前置依赖**——写进"超出范围的观察"提示用户走 `cs-refactor`，本 feature 照常推进 - 选"不做"也要列评估观察点（文件级 + 目录级），不能只写一句"健康"——避免后续 acceptance 时无法回看判断依据 -- "建议沉淀的 convention"判定**稳定模式 vs 一次性整理**：稳定模式 = 这条规则**未来其他 feature 也应该遵守**（如归属规则、命名规则）；一次性整理 = 只是这个目录恰好挤了，没有普适规则。拿不准时倾向"一次性整理"——design 阶段方案还没真跑过，不在这里直接归档，只留钩子让 implement 跑通后由用户决定是否走 `cs-decide` +- "建议沉淀的 convention"判定**稳定模式 vs 一次性整理**：稳定模式 = 这条规则**未来其他 feature 也应该遵守**（如归属规则、命名规则）；一次性整理 = 只是这个目录恰好挤了，没有普适规则。拿不准时倾向"一次性整理"——design 阶段方案还没真跑过，不在这里直接归档，只留钩子让 implement 跑通后由用户决定是否走 `cs-keep` - "超出范围的观察"和"建议沉淀的 convention"都是发现到就提，不是必填——发现不到就省略整段 写完此节不单独走确认，随整稿一起进整体 review（看下文第 5 节）。 @@ -218,13 +216,11 @@ implement 完成的判据，acceptance 核对的依据。**不写测试代码 / 预判 acceptance 阶段要把哪些东西**提炼**回 architecture（不是加个 design 链接就算数）： -- **名词** ← 系统级可见的实体 / 类型 / 对外契约 → architecture 的"结构与交互 / 数据与状态"节 -- **动词骨架** ← 跨模块可见的主流程 / 关键编排 → architecture 的结构图 / 模块交互 -- **流程级约束** ← 跨 feature 稳定的约束（错误语义、幂等、扩展点、挂载点规约）→ architecture 的"已知约束" +- **名词** ← 系统级可见的实体 / 类型 / 对外契约 → 进 `requirements/CONTEXT.md` 术语表 +- **动词骨架** ← 跨模块可见的主流程 / 关键编排 → 若涉及结构性选择就写一条 ADR +- **流程级约束** ← 跨 feature 稳定的约束（错误语义、幂等、扩展点、挂载点规约）→ 若难以回退且有真实权衡就写一条 ADR -外加：关联哪些已有架构 doc；架构总入口要不要新增描述（描述不是贴链接）。 - -纯模块内部不可见的改动，写"本 feature 改动局限在 {模块} 内部，无系统级可见变化"，acceptance 核实后跳过归并。 +纯模块内部不可见的改动，写"本 feature 改动局限在 {模块} 内部，无系统级可见变化"，acceptance 核实后跳过这一节。 ## 5. review 提示 diff --git a/cs-feat-ff/SKILL.md b/cs-feat-ff/SKILL.md index 77f2ea3..c816db0 100644 --- a/cs-feat-ff/SKILL.md +++ b/cs-feat-ff/SKILL.md @@ -9,7 +9,7 @@ description: feature 流程的超轻量通道——不写 design / checklist 直 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 -用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护；动手后回写一份**最简的 `{slug}-ff-note.md`** 让这次工作可追溯、可被 cs-arch / cs-req backfill 看到、能纳入 scoped-commit 提交。 +用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护；动手后回写一份**最简的 `{slug}-ff-note.md`** 让这次工作可追溯、可被 cs-req / cs-domain backfill 看到、能纳入 scoped-commit 提交。 很轻：没有 design doc / checklist / 验收清单 / 动手前的用户确认。看完指引，该读代码读、该写代码写、写完回写一段话。 @@ -19,14 +19,13 @@ description: feature 流程的超轻量通道——不写 design / checklist 直 Glob `.codestable/` 发现可用目录和文档，按需取用： -- **`architecture/`** — ARCHITECTURE.md 总入口 + 子系统 doc。改跨模块的东西前看一眼避免违反边界 -- **`compound/`** — learning / trick / decision / explore 四类沉淀： +- **`requirements/CONTEXT.md`** — 领域术语；用项目术语命名，不自己造名 +- **`requirements/adrs/`** — 已拍板的架构决策；改跨模块的东西前 grep 相关 adr 避免违反 +- **`compound/`** — 沉淀的坑点 / 技巧 / 调研： ```bash - python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --query "关键词" - python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --query "关键词" - python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --query "关键词" + grep -r "关键词" .codestable/compound/ ``` -- **`requirements/`** — 有相关 req 时读边界 +- **`requirements/{slug}.md`** — 有相关 req 时读边界 - **`features/`** — 有同类 feature 时参考其 design - **`reference/`** — shared-conventions.md / tools.md @@ -36,8 +35,8 @@ Glob `.codestable/` 发现可用目录和文档，按需取用： 动手前问 2 个问题： -1. **这块代码以前有人栽过跟头吗？** → 搜 `compound/` 的 learning -2. **这块代码有没有已经拍板的写法约束？** → 搜 `compound/` 的 decision + 看 `architecture/` 相关子系统 +1. **这块代码以前有人栽过跟头吗？** → `grep -r "关键词" .codestable/compound/` +2. **这块代码有没有已经拍板的写法约束？** → 看 `requirements/adrs/` 相关 ADR + grep `compound/` 找写法沉淀 命中就把结论融进实现（**按约束来写**，不是抄）。没命中按自己判断写很正常。搜不到换几个关键词再试。 @@ -170,7 +169,7 @@ tags: [...] - **不写 design doc / checklist / acceptance**——这就是 fastforward 的意义。要写就去 `cs-feat-design` - **不跟用户确认方案**——用户让你做小功能就是不想等你开会 -- **不在 `.codestable/` 里留 `{slug}-ff-note.md` 之外的新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-learn` / `cs-trick` 写 +- **不在 `.codestable/` 里留 `{slug}-ff-note.md` 之外的新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-keep` 写 --- @@ -180,7 +179,7 @@ tags: [...] - 改动涉及 3 个以上子系统 - 需要引入新术语或和现有术语冲突 -- 要动 `.codestable/architecture/` 既定的模块边界 +- 要打破 `.codestable/requirements/adrs/` 既定的模块边界 ADR - 用户追加的要求让范围翻倍 切回方式：触发 `cs-feat-design`。已写的代码在 design 里标"已部分实现"即可。 @@ -206,10 +205,8 @@ tags: [...] 按 `shared-conventions.md` 第 3 节"feature-ff"收尾推荐顺序逐项一句话提示（用户"不用"立即跳过）： -1. 暴露的坑 → "沉淀 learning？（`cs-learn`）" -2. 拍板的长期约束 → "归档决定？（`cs-decide`）" -3. 快速改动影响 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）" -4. 最后问是否代为 scoped-commit +1. 暴露的坑或拍板的长期约束 → "沉淀到 compound？（`cs-keep`）" +2. 最后问是否代为 scoped-commit --- diff --git a/cs-feat-impl/SKILL.md b/cs-feat-impl/SKILL.md index a8ea675..8b61325 100644 --- a/cs-feat-impl/SKILL.md +++ b/cs-feat-impl/SKILL.md @@ -120,7 +120,7 @@ design 给的 `steps` 是 paradigm 维度切片（编排骨架 → 计算节点 **不要合并到下一步**——一旦混在一起，行为变更和结构变更就分不开，出问题回滚不到干净中间态 - 如果 2.5 结论是"不做"但写到中途反射检查触发了拆分信号 → 走下面"反射检查"那条路径（停下来 → 和用户对齐 → 能 provable 解决就追加独立 step），**不要绕过用户确认偷偷追加** -- 如果 2.5 末尾有"建议沉淀的 convention"段：implement 阶段**不主动归档**——只在重组目录跑通且行为零改动确认后，在汇报里带一句"design 2.5 建议沉淀的 convention 已就绪，等 acceptance 阶段确认是否走 cs-decide"，把决定权交给 acceptance / 用户 +- 如果 2.5 末尾有"建议沉淀的 convention"段：implement 阶段**不主动归档**——只在重组目录跑通且行为零改动确认后，在汇报里带一句"design 2.5 建议沉淀的 convention 已就绪，等 acceptance 阶段确认是否走 cs-keep"，把决定权交给 acceptance / 用户 --- diff --git a/cs-feat/SKILL.md b/cs-feat/SKILL.md index 0da6339..65020e1 100644 --- a/cs-feat/SKILL.md +++ b/cs-feat/SKILL.md @@ -127,4 +127,4 @@ brainstorm 是讨论层独立入口，会分诊：case 1（清楚 → 直接 des - `.codestable/reference/system-overview.md` — CodeStable 体系总览 - `.codestable/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、checklist 生命周期 - `.codestable/attention.md` — CodeStable 启动注意事项和项目硬约束 -- 项目架构总入口 — 方案设计阶段需要查 +- `.codestable/requirements/CONTEXT.md` + `requirements/adrs/` — 方案设计阶段需要查的领域术语与拍板决策 diff --git a/cs-issue-analyze/SKILL.md b/cs-issue-analyze/SKILL.md index 58d3e03..d1cc590 100644 --- a/cs-issue-analyze/SKILL.md +++ b/cs-issue-analyze/SKILL.md @@ -26,7 +26,7 @@ description: issue 流程阶段 2——读 report + 读代码定位根因、评 3. **把上下文读全**： - 问题报告全文 + `.codestable/attention.md` - 报告里提到的相关文件（用 Glob / Grep 找别只凭描述） - - **扫 .codestable/ 全局**——Glob `.codestable/` 发现可用输入，按需取用：`architecture/`（涉及跨模块时读 ARCHITECTURE.md）、`compound/`（用 search-yaml.py 搜相关 trick / explore / learning，命中在分析开头标注引用）、`requirements/`（涉及能力边界时读） + - **扫 .codestable/ 全局**——Glob `.codestable/` 发现可用输入，按需取用：`requirements/CONTEXT.md` + `requirements/adrs/`（涉及领域术语 / 拍板决策时读）、`compound/`（`grep -r` 关键词搜历史沉淀，命中在分析开头标注引用）、`requirements/{slug}.md`（涉及能力边界时读） --- diff --git a/cs-issue-fix/SKILL.md b/cs-issue-fix/SKILL.md index 0cfc69a..dab0600 100644 --- a/cs-issue-fix/SKILL.md +++ b/cs-issue-fix/SKILL.md @@ -41,8 +41,7 @@ gate 不通过就先处理 findings，不把"测试已过"当成完成。gate 1. **方案已确认**——读 analysis，确认 `doc_type=issue-analysis` 且 `status=confirmed`，第 5 节用户选定了哪个方案 2. **上下文读全**：analysis 全文 + report 全文 + analysis 第 1 节定位的所有代码 + `.codestable/attention.md` + 沉淀目录搜索： - - `python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter status=active --query "{关键词}"`——确认修复方式不违背已有库用法 / 模式 - - 同样命令换 `--filter doc_type=explore`——确认修复点和已有证据不冲突 + - `grep -r "{关键词}" .codestable/compound/`——确认修复方式不违背已有库用法 / 模式 / 调研结论 3. **确认起点**——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手 ### 快速通道（无 analysis，从 report 直接触发） @@ -144,11 +143,9 @@ issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该 按 `shared-conventions.md` 第 3 节"issue-fix"收尾推荐顺序各问一句（用户"不用"立即跳过）： 0. 完成后先进入 `cs-code-review` 做独立 diff 评审；Critical/Important 未清零不进 commit，scoped-commit 发起权归 `cs-code-review`。 -1. 暴露了值得复用的坑点 → "沉淀 learning？（`cs-learn`）" -2. 沉淀出长期约束 / 规约 / 技术决定 → "归档决定？（`cs-decide`）" -3. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）" -4. 修复暴露了 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆不一致 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）" -5. 最后问是否代为提交。同意时按收尾提交规则执行 +1. 暴露的坑点 / 长期约束 / 规约 / 技术决定 → "沉淀到 compound？（`cs-keep`）" +2. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）" +3. 最后问是否代为提交。同意时按收尾提交规则执行 建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue-report` 处理别塞这个 PR。 diff --git a/cs-issue/SKILL.md b/cs-issue/SKILL.md index c62417b..9eafe6e 100644 --- a/cs-issue/SKILL.md +++ b/cs-issue/SKILL.md @@ -101,4 +101,4 @@ issue 工作流在"看到问题"和"动手改代码"之间塞缓冲： - `.codestable/reference/system-overview.md` — CodeStable 体系总览 - `.codestable/reference/shared-conventions.md` — 跨阶段共享口径 - `.codestable/attention.md` — CodeStable 启动注意事项和项目硬约束 -- `.codestable/architecture/ARCHITECTURE.md` — 根因分析时可能要查 +- `.codestable/requirements/CONTEXT.md` + `requirements/adrs/` — 根因分析时可能要查的领域术语与拍板决策 diff --git a/cs-keep/SKILL.md b/cs-keep/SKILL.md new file mode 100644 index 0000000..5f093ca --- /dev/null +++ b/cs-keep/SKILL.md @@ -0,0 +1,18 @@ +--- +name: cs-keep +description: 把刚发现的坑、技巧、决策、调研沉淀到 .codestable/compound/，纯 markdown 文件，靠 grep 检索。触发：用户说"记下来"、"沉淀一下"、"留个 note"，或 cs-feat-accept / cs-issue-fix / cs-feat-design / cs-issue-analyze 收尾时推送。 +--- + +# cs-keep + +先读 `.codestable/attention.md`；缺失就提示跑 `cs-onboard`。 + +把这次值得记的事写到 `.codestable/compound/YYYY-MM-DD-{slug}.md`： + +- `{slug}` kebab-case，30 字内，能让自己半年后看一眼标题就想起来是啥 +- 纯 markdown，没有 frontmatter +- 三段足够：**背景**（这事是什么场景下冒出来的）/ **结论**（实际记的那一条）/ **证据**（代码片段、路径、命令、链接，任何能让别人复核的） + +写完报路径就完事。不要追问"还要不要分类"、"要不要写 tags"——没这些东西。 + +未来要找回来直接 `grep -r "关键词" .codestable/compound/`。 diff --git a/cs-learn/SKILL.md b/cs-learn/SKILL.md deleted file mode 100644 index 6a8ec27..0000000 --- a/cs-learn/SKILL.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -name: cs-learn -description: 把踩过的坑或好做法沉淀成可检索的 learning 文档，两条轨道 pitfall（坑）/ knowledge（默认做法）。触发：用户说"沉淀知识"、"learning"、"把这次经验记下来"，或 acceptance / fix 收尾时推送。 ---- - -# cs-learn - -## 启动必读 - -开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 - -每次做 feature 或修 issue 都会留下 spec 文件。但 spec 记录的是"做了什么"和"怎么做的"，**不会记录"踩了什么坑"和"发现了什么更好的做法"**。没有沉淀的团队总在重复解决同一个问题。 - -两条轨道： - -- **坑点轨道**（pitfall）：记录问题 / 根因 / 解法，防止下次再掉进同一个坑 -- **知识轨道**（knowledge）：记录最佳实践 / 工作流改进 / 可复用模式 - -两者都写入 `.codestable/compound/`（共享目录见 `shared-conventions.md` 第 1 节"归档类文档"）。本技能产出 frontmatter 带 `doc_type: learning`，命名 `YYYY-MM-DD-learning-{slug}.md`。 - ---- - -## 什么时候触发 - -| 情境 | 说明 | -|---|---| -| 完成 feature 工作流 | `cs-feat-accept` 主动问"要记录这次的学习点吗？" | -| 完成 issue 工作流 | `cs-issue-fix` 主动问"要把这个坑记录下来吗？" | -| 用户主动 | "记录一下"、"沉淀知识"、"learning"等 | -| 解决了一次性难题 | 不在 feature / issue 内但花了大量时间才解决的工程问题 | - -主动推荐一句话即可，用户说"不用了"立刻跳过——重复推可能让用户觉得 AI 在加戏。 - ---- - -## 两条轨道各写什么 - -**坑点**：调试过的 bug / 绕过的配置陷阱 / 环境问题 / 集成失败……一切"本来应该好但没好"的经历。 - -**知识**：发现的最佳实践 / 工作流改进 / 架构洞见 / 可复用设计模式……一切"以后应该默认这样做"的学习。 - -frontmatter / 正文模板 / 完整示例见同目录 `reference.md`。 - ---- - -## 工作流阶段 - -### Phase 1：识别来源（自动） - -从对话上下文提取： - -- **来源类型**：feature 工作流 / issue 工作流 / 独立问题 -- **关联产物**：feature 目录 / issue 目录路径（如有） -- **粗分轨道**：坑点 or 知识。"修了什么坏了的东西" = 坑点；"发现了什么更好做法" = 知识。两者都有就分两条 - -来源不明确问用户**一个问题**澄清不要猜。 - -### Phase 1.5：查重叠与意图分流（必做） - -按 `shared-conventions.md` §6 第 5/6 条： - -- 含"改 / 更新 / 补充 / 某条 learning"或指向某份旧文档 → 直接走**更新已有** -- 否则用搜索工具按 `--filter tags~=` 或 `--query` 查一遍，命中相近旧文档时把候选列给用户 - -**更新路径**：读旧文档 → 和用户对齐要改哪几节（常见是补新踩的坑、补当时"没找到原因"的根因）→ 起草 diff → 写回原文件 + `updated: YYYY-MM-DD`，不新建。 - -### Phase 2：提炼要点（一次一个问题） - -**坑点轨道**问： - -1. "你最开始观察到的现象是什么？" -2. "哪些解法试过但没用？"（鼓励写，失败的尝试是后人最宝贵的信息——知道哪条路不通能省下大量时间） -3. "最终怎么发现真正原因的？" -4. "下次可以更早发现吗？怎么发现？" - -**知识轨道**问： - -1. "你发现的这个模式，在什么情境下最有价值？" -2. "不这样做会出什么问题？" -3. "有没有不适用的反例？" - -用户对某问题说"没什么"或"跳过"就跳过——宁可少一节也不用空话填充。 - -### Phase 3：起草 + 用户 review - -AI 一次性起草完整文档（YAML frontmatter + 所有正文节）。一次性展示给用户。 - -### Phase 4：归档 - -- 新建：写入 `compound/YYYY-MM-DD-learning-{slug}.md`（日期取**归档当天**），frontmatter 带 `doc_type: learning` -- 更新：写回 Phase 1.5 定位的原文件 + `updated: YYYY-MM-DD` -- supersede：按 `shared-conventions.md` §6 第 5 条处理 - -### Phase 5：可发现性检查 - -写完若发现一两行"每次 CodeStable 技能启动都该知道"的项目硬约束，提示用户用 `cs-note` 追加到 `.codestable/attention.md`。不要自作主张改 attention，也不要写外部 AI 入口。 - ---- - -## 搜索工具 - -> 完整语法见 `.codestable/reference/tools.md`。 - -```bash -# 按轨道筛选坑点 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=pitfall --filter severity=high - -# 按组件查相关学习点 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter component~={组件名} - -# 归档后查重叠 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter tags~={主要 tag} --json -``` - ---- - -## 守护规则 - -> 归档类共享规则见 `shared-conventions.md` 第 6 节。本技能特有： - -1. **不混入 spec**——learning 不放进 `features/` 或 `issues/`；spec 也不放进 `compound/` -2. **只认自己的 doc_type**——只读写 `doc_type: learning` diff --git a/cs-learn/reference.md b/cs-learn/reference.md deleted file mode 100644 index 1570cd9..0000000 --- a/cs-learn/reference.md +++ /dev/null @@ -1,55 +0,0 @@ -# learning 参考模板 - -本文件提供 `cs-learn` 的两条轨道模板和示例。产出文档写入 `.codestable/compound/`，文件名 `YYYY-MM-DD-learning-{slug}.md`。 - -## 1. 坑点轨道（pitfall） - -### frontmatter - -```yaml ---- -doc_type: learning -track: pitfall -date: YYYY-MM-DD -slug: {英文描述，连字符分隔} -component: {受影响模块/层} -severity: low | medium | high -tags: [] ---- -``` - -### 正文结构 - -1. 问题 -2. 症状 -3. 没用的做法 -4. 解法 -5. 为什么有效 -6. 预防 - -## 2. 知识轨道（knowledge） - -### frontmatter - -```yaml ---- -doc_type: learning -track: knowledge -date: YYYY-MM-DD -slug: {英文描述，连字符分隔} -component: {适用模块/领域} -tags: [] ---- -``` - -### 正文结构 - -1. 背景 -2. 指导原则 -3. 为什么重要 -4. 何时适用 -5. 示例 - -## 3. 示例 - -完整示例可按仓库需要逐步补充；当前技能正文只保留流程，不再内嵌长示例。 diff --git a/cs-note/SKILL.md b/cs-note/SKILL.md index f442207..7211ccd 100644 --- a/cs-note/SKILL.md +++ b/cs-note/SKILL.md @@ -9,9 +9,9 @@ description: 把"短到不值得起一份文件、但 AI 每次启动 CodeStable 开始任何判断或动作前，先检查 `.codestable/attention.md`：存在就读取；缺 `.codestable/` 就提示先运行 `cs-onboard`；只有 attention.md 缺失时，本技能可以先创建固定分节骨架再写入。不要回退到外部 AI 入口文件。 -cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，**通过检索**被读到；`.codestable/attention.md` 是 CodeStable 技能启动时的**强制必读**上下文。这两类信息归宿不同——本技能专管后者：把"短、稳、每次都要知道"的碎片追加到 attention 文件里。 +`cs-keep` 产出独立 markdown 文件到 `.codestable/compound/`，**通过 grep 检索**被读到；`.codestable/attention.md` 是 CodeStable 技能启动时的**强制必读**上下文。这两类信息归宿不同——本技能专管后者：把"短、稳、每次都要知道"的碎片追加到 attention 文件里。 -不替代沉淀类技能，是补一个之前缺的入口。 +不替代 cs-keep，是另一个入口。 --- @@ -21,10 +21,10 @@ cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，**通过检索** | 项 | 进 cs-note | 走别处 | |---|---|---| -| 长度 | 一两行能讲清 | 超过半屏 / 需要展开背景 → cs-learn | -| 频次 | 几乎每次会话都用得上 | 只在某类具体任务相关 → cs-trick | +| 长度 | 一两行能讲清 | 超过半屏 / 需要展开背景 → cs-keep | +| 频次 | 几乎每次会话都用得上 | 只在某类具体任务相关 → cs-keep | | 稳定度 | 项目长期生效的硬约束 | 临时绕过 / 短期 workaround → 写到 issue spec 或 feature spec | -| 拍板状态 | 已既成事实（不需要决策记录） | 需要记选型理由 / 拒方案 → cs-decide | +| 拍板状态 | 已既成事实（不需要决策记录） | 需要记选型理由 / 拒方案 → cs-keep | ✅ **典型该进**： @@ -37,11 +37,11 @@ cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，**通过检索** ❌ **典型不该进**（会让 attention.md 膨胀）： -- 某个 bug 的修法（→ cs-learn pitfall） -- 某个库怎么用（→ cs-trick library） -- 一段架构说明（→ .codestable/architecture/） +- 某个 bug 的修法（→ cs-keep） +- 某个库怎么用（→ cs-keep） +- 一段架构说明（→ cs-domain 起一条 ADR） - "本周在做 X"这种短期状态（→ 别记，会过期） -- 需要 3 行以上才讲清的（→ cs-learn knowledge） +- 需要 3 行以上才讲清的（→ cs-keep） **判不准就反问用户一句**："这条以后是不是每次会话都要让 AI 知道？"答"不一定" → 不是 cs-note。 @@ -89,7 +89,7 @@ attention.md 是 CodeStable 自己的启动注意事项入口，价值来自所 - 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节） - 分节为空时整段保留，不删（让 AI 看到这一节是有意义的） - 注释行 `` 是本技能的识别锚——找不到就在文件末尾插入整块结构 -- **整段长度软上限 ~150 行**——超过提示用户："碎片知识太多了，挑几条沉到 cs-learn / cs-decide 里？" +- **整段长度软上限 ~150 行**——超过提示用户："碎片知识太多了，挑几条沉到 cs-keep 里？" --- @@ -132,7 +132,7 @@ attention.md 是 CodeStable 自己的启动注意事项入口，价值来自所 写完看一眼"项目碎片知识"段总行数： -- ≥150 行 → 提示用户挑几条沉到 cs-learn / cs-decide +- ≥150 行 → 提示用户挑几条沉到 cs-keep - "其他"分节 ≥5 条 → 提示用户讨论是否新增固定分节 只是**提示**，不替用户决定。 @@ -152,7 +152,7 @@ attention.md 是 CodeStable 自己的启动注意事项入口，价值来自所 ## 容易踩的坑 -- 把详细背景 / 多步骤指南塞进 attention.md——超过两行就该走 cs-learn +- 把详细背景 / 多步骤指南塞进 attention.md——超过两行就该走 cs-keep - 写到 `AGENTS.md` / `CLAUDE.md`——CodeStable 不再兼容这些外部入口 - 默默新增分节——分节是写死的，新增要先和用户讨论 - 看到一条就连带把其他几条也写进去——一次一条 diff --git a/cs-onboard/SKILL.md b/cs-onboard/SKILL.md index af9a79c..0a54294 100644 --- a/cs-onboard/SKILL.md +++ b/cs-onboard/SKILL.md @@ -28,8 +28,7 @@ description: 把新仓库或有零散文档的仓库接入 CodeStable 体系， .codestable/ ├── attention.md CodeStable 技能启动必读的项目注意事项 ├── requirements/ 需求聚合根（空目录 .gitkeep） -├── architecture/ -│ └── ARCHITECTURE.md 架构总入口（首次创建为占位模板） +│ （CONTEXT.md / adrs/ 由 cs-domain 按需 lazy 创建） ├── roadmap/ 规划层聚合根 ├── goals/ 目标聚合根（bounded goal 自主迭代 + 功能验收） ├── features/ feature 聚合根 @@ -38,7 +37,7 @@ description: 把新仓库或有零散文档的仓库接入 CodeStable 体系， ├── audits/ 审计聚合根 ├── brainstorms/ 脑暴 / interview 持久记录聚合根 ├── brainstorm/ 脑暴 spike 实验代码区（验完结论回写 brainstorms note） -├── compound/ 沉淀类统一目录（learning / trick / decision / explore） +├── compound/ 沉淀类统一目录（cs-keep 写自由 markdown，grep 检索） ├── tools/ 跨工作流共享脚本（onboard 整目录释放） │ ├── search-yaml.py / validate-yaml.py │ ├── codestable-worktree-gate.py / codestable-ai-branch-guard.py / codestable-main-publish.py @@ -76,7 +75,7 @@ description: 把新仓库或有零散文档的仓库接入 CodeStable 体系， **步骤 1：和用户确认范围** -- 项目名 / 简介（用于填 `ARCHITECTURE.md` 占位） +- 项目名 / 简介（汇报时引用） - attention.md 只建最小骨架；用户已经给出的项目硬约束才写入，不凭空代填 **步骤 2：创建目录骨架** @@ -85,11 +84,12 @@ description: 把新仓库或有零散文档的仓库接入 CodeStable 体系， - `.codestable/{requirements,roadmap,goals,features,issues,refactors,audits,brainstorms,brainstorm,compound}/.gitkeep` - `.codestable/attention.md`（最小骨架模板见同目录 `reference.md`） -- `.codestable/architecture/ARCHITECTURE.md`（占位模板见同目录 `reference.md`） - `.codestable/tools/`（用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录拷贝技能包 `cs-onboard/tools/`，**不要 Read 再 Write**） - `.codestable/reference/`（同上） - `.codestable/hooks/`（同上；可选的分支保护层，见下文「分支保护 hook」） +`requirements/CONTEXT.md` 和 `requirements/adrs/` 不在骨架里——交给 `cs-domain` 在用户第一次需要术语 / ADR 时 lazy 创建。 + > **落盘用 shell 整目录覆盖**，不要 Read 再 Write——这两个目录是机器共享资产，Read+Write 会截断大文件、改缩进、吃空行，还慢费 token。具体命令见迁移路径步骤 4。 **步骤 3：attention.md 提醒** @@ -100,7 +100,7 @@ attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编 列建了哪些文件： -> CodeStable 骨架已就绪。现在可以：开始新功能 `cs-feat` / 报告问题 `cs-issue` / 沉淀知识 `cs-learn` +> CodeStable 骨架已就绪。现在可以：开始新功能 `cs-feat` / 报告问题 `cs-issue` / 沉淀知识 `cs-keep` --- @@ -110,7 +110,8 @@ attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编 | 现有文件 | 推测内容类型 | 建议归入 CodeStable | 置信度 | |---|---|---|---| -| `docs/DESIGN.md` | 项目架构 | `.codestable/architecture/ARCHITECTURE.md` | 高 | +| `docs/glossary.md` | 领域术语 | `.codestable/requirements/CONTEXT.md`（cs-domain 写） | 高 | +| `docs/adr-*.md` | 架构决策 | `.codestable/requirements/adrs/NNN-{slug}.md` | 高 | | `docs/feature-auth.md` | 功能设计稿 | `.codestable/features/YYYY-MM-DD-auth/auth-design.md` | 中 | | `SPEC.md` | 功能需求？ | 需用户确认 | 低 | @@ -170,7 +171,7 @@ Copy-Item -Recurse -Force <技能包路径>\cs-onboard\hooks\* .codestable\ ## 骨架文件模板 -`ARCHITECTURE.md` 占位模板和 `attention.md` 最小模板见同目录 `reference.md`。 +`attention.md` 最小模板见同目录 `reference.md`。 --- @@ -186,10 +187,9 @@ Copy-Item -Recurse -Force <技能包路径>\cs-onboard\hooks\* .codestable\ ## 退出条件 -- [ ] `.codestable/` 各聚合根目录（requirements/architecture/roadmap/goals/features/issues/refactors/audits/brainstorms/compound）都存在 +- [ ] `.codestable/` 各聚合根目录（requirements/roadmap/goals/features/issues/refactors/audits/brainstorms/compound）都存在 - [ ] `.codestable/attention.md` 已建 - [ ] `.codestable/tools/`、`.codestable/reference/`、`.codestable/hooks/` 已从技能包复制 -- [ ] `.codestable/architecture/ARCHITECTURE.md` 已建 - [ ] 已告知 owner 分支保护 hook 是可选项及如何接入 / 关闭 - [ ] 迁移路径：每条映射都有明确处理结果（迁移 / 保留原位） - [ ] 迁移路径：没有未经确认就移动的文件 @@ -215,4 +215,3 @@ Copy-Item -Recurse -Force <技能包路径>\cs-onboard\hooks\* .codestable\ - `.codestable/reference/system-overview.md` — CodeStable 体系总览 - `.codestable/reference/shared-conventions.md` — 目录结构和共享口径的权威版本 - `.codestable/attention.md` — CodeStable 技能启动必读的项目注意事项 -- `.codestable/architecture/ARCHITECTURE.md` — 架构总入口骨架 diff --git a/cs-onboard/reference.md b/cs-onboard/reference.md index 516bd7f..964d185 100644 --- a/cs-onboard/reference.md +++ b/cs-onboard/reference.md @@ -2,26 +2,7 @@ 本文件提供 `cs-onboard` 使用的骨架模板。 -## 1. `.codestable/architecture/ARCHITECTURE.md` 占位模板 - -```markdown -# {项目名} 架构总入口 - -> 状态：骨架（待填充） -> 创建日期：YYYY-MM-DD - -## 1. 项目简介 - -## 2. 核心概念 / 术语表 - -## 3. 子系统 / 模块索引 - -## 4. 关键架构决定 - -## 5. 已知约束 / 硬边界 -``` - -## 2. `.codestable/attention.md` 最小模板 +## `.codestable/attention.md` 最小模板 attention.md 是 CodeStable 技能启动必读的项目注意事项入口。onboard 创建最小骨架，不替项目 owner 填实质内容；后续短规则由 `cs-note` 追加。 diff --git a/cs-onboard/reference/requirement-example.md b/cs-onboard/reference/requirement-example.md index edc3de8..4c5b2b5 100644 --- a/cs-onboard/reference/requirement-example.md +++ b/cs-onboard/reference/requirement-example.md @@ -15,7 +15,7 @@ description: 一份好的 requirement doc 长什么样——供 cs-req 起草时 - **用户故事顶在最前面**，每条要能想象出一个具体处境。 - **为什么需要 / 怎么解决 各一段短的**，不上课、不展开。 - **边界用列表**，至少写一条"它不管什么"。 -- **不写实现细节**——"通过 X 接口调用 Y 服务"这种挪到 architecture doc。 +- **不写实现细节**——"通过 X 接口调用 Y 服务"这种结构性决策走 ADR（cs-domain）。 - **frontmatter 的 `pitch`** 要去技术化、一句话、读者没上下文也能看懂，以后当宣传词用。 --- @@ -85,4 +85,4 @@ tags: [debug, ai-assist] > 通过调用代码检索服务和 Git 日志分析模块，对报错日志进行上下文推理…… -这是 architecture doc 的事，从 requirement 里删掉。 +这是结构性决策，走 ADR（cs-domain），从 requirement 里删掉。 diff --git a/cs-onboard/reference/shared-conventions.md b/cs-onboard/reference/shared-conventions.md index 32243d8..e0e58c5 100644 --- a/cs-onboard/reference/shared-conventions.md +++ b/cs-onboard/reference/shared-conventions.md @@ -13,12 +13,17 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： ``` .codestable/ ├── attention.md CodeStable 技能启动必读的项目注意事项 -├── requirements/ 能力愿景层（"用户需要什么、系统提供什么能力来满足"，过去/现在/未来） -│ ├── VISION.md 中心索引（按 status 分组，每条带 pitch 一句话） -│ └── {slug}.md 一个能力一份，扁平（cs-req 产出） -├── architecture/ 架构中心目录（"用什么结构实现"，只记现状） -│ ├── ARCHITECTURE.md 总入口（索引 + 关键架构决定） -│ └── {type}-{slug}.md 子系统 / 模块 doc（cs-arch 产出） +├── requirements/ 能力愿景 + 领域模型 + 决策记录 +│ ├── VISION.md 能力中心索引（cs-req 维护） +│ ├── {slug}.md 一个能力一份，扁平（cs-req 产出） +│ ├── CONTEXT.md 领域术语表（cs-domain lazy 创建；多 context 时被 CONTEXT-MAP.md 替代） +│ ├── CONTEXT-MAP.md 多 context 拓扑入口（cs-domain，仅多 context 时存在） +│ ├── adrs/ 架构决策记录（cs-domain，lazy 创建） +│ │ └── NNN-{slug}.md Nygard 四节 + 状态机 frontmatter +│ └── {ctx}/ 子 context 子目录（仅多 context 时存在） +│ ├── CONTEXT.md 子 context 术语 +│ ├── adrs/ 子 context 特定 ADR +│ └── {capability}.md 归属本 context 的能力 ├── roadmap/ 规划层（"接下来怎么做这块大需求 + 模块怎么切 + 接口怎么定"） │ └── {slug}/ 一个大需求一个子目录（cs-roadmap 产出） │ ├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分 / 接口契约 / 子 feature 清单 / 排期 @@ -52,9 +57,9 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： │ ├── {slug}-refactor-design.md │ ├── {slug}-checklist.yaml │ └── {slug}-apply-notes.md -├── compound/ 沉淀类文档统一目录 -│ └── YYYY-MM-DD-{doc_type}-{slug}.md -│ doc_type ∈ {learning, trick, decision, explore} +├── compound/ 沉淀类文档统一目录（cs-keep 产出） +│ └── YYYY-MM-DD-{slug}.md +│ 纯 markdown，无 frontmatter，grep 检索 ├── brainstorm/ brainstorm 阶段 spike 实验代码区（cs-brainstorm 临时产出） │ └── {slug}/ 一次 spike 一个子目录，文件名随意 │ 验完不强制清理，结论回写到对应 brainstorm note @@ -67,21 +72,16 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： - 需求文档：`requirements/{slug}.md`（能力愿景，不带日期前缀，扁平不分组）；中心索引 `requirements/VISION.md` - roadmap：`roadmap/{slug}/`（不带日期前缀，平铺不嵌套） - feature / issue / refactor 目录：带日期前缀 `YYYY-MM-DD-{slug}` -- 沉淀类：`compound/YYYY-MM-DD-{doc_type}-{slug}.md`，日期用**归档当天** -- 架构 doc：`architecture/{type}-{slug}.md`（长效，不带日期前缀）；总入口固定 `ARCHITECTURE.md` +- 沉淀类：`compound/YYYY-MM-DD-{slug}.md`，日期用**归档当天**，纯 markdown 无 frontmatter（cs-keep 产出） +- 领域术语：`requirements/CONTEXT.md`（单 context）或 `requirements/{ctx}/CONTEXT.md`（多 context）；cs-domain lazy 创建 +- 架构决策：`requirements/adrs/NNN-{slug}.md`（系统级）或 `requirements/{ctx}/adrs/NNN-{slug}.md`（子 context）；3 位编号，cs-domain 产出 - 项目注意事项入口固定为 `.codestable/attention.md`，所有 CodeStable 子技能启动前必须读取；不再兼容 `AGENTS.md` / `CLAUDE.md` 等外部入口 -### 架构 doc 分组规则（同类聚合） +### 单 context ↔ 多 context 拓扑 -`architecture/` 下用文件名第一段作 type 标记：`ui-chat.md` 和 `ui-events.md` 同 `ui` 类。**所有架构 doc 必须 `{type}-{slug}.md`**——只有一份的也要带合理 type 段（如 `cli-entry.md`），否则未来同类出现时聚合不了。 - -**触发**：某 type 在 `architecture/` 根目录达到 ≥6 份时（即新加第 6 份那次），把这一类全部收进同名子目录。 - -**收入后**：去掉 type 前缀。`ui-chat.md` → `ui/chat.md`。 - -**只升不降**：删到 ≤5 份也不折回平铺。 - -**触发时谁负责**：`cs-arch` 的 `backfill` / `update` 模式在 Phase 6 落盘前主动检查并搬迁；命中阈值时这次操作要把"本次新加 / 改的 + 已有同类全部"一起搬，并同步改 `ARCHITECTURE.md` 链接（搬迁本身要在 Phase 5 给用户 review，不偷偷做）。`check` 模式不主动搬迁，但发现 ≥6 仍平铺时在报告末尾列为观察项。 +- `requirements/CONTEXT-MAP.md` 存在 → 多 context 模式：术语和 ADR 按子 context 分目录 +- 只有 `requirements/CONTEXT.md` → 单 context：术语和 ADR 平铺在 `requirements/` 下 +- 升级路径见 `cs-domain` 的"单 → 多 context 升级"节 ### 改目录结构 @@ -97,16 +97,9 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： **issue spec**：report / analysis / fix-note 共用 `doc_type` / `issue` / `status` / `tags`。`severity` / `root_cause_type` / `path` 由对应阶段按需补。 -**归档类（compound）**： +**归档类（compound）**：由 `cs-keep` 统一产出，写到 `.codestable/compound/YYYY-MM-DD-{slug}.md`。纯 markdown，**无 frontmatter**。三段足够：背景 / 结论 / 证据。检索靠 grep。 -- learning / trick / decision / explore 四类**统一写入 `.codestable/compound/`** -- 每个文档 frontmatter 顶部带 `doc_type`（learning / trick / decision / explore）作跨子技能归属判定 -- 文件名 `YYYY-MM-DD-{doc_type}-{slug}.md`——日期打头便于 `ls` 排序，type 段在中间便于 grep -- 各子技能在 `doc_type` 之外保留专属 frontmatter（learning 的 `track` / trick 的 `type` / decision 的 `category` / explore 的 `type`） -- 各子技能只认自己的 `doc_type` 不读写别家 -- `status` 等通用字段语义和本文件保持一致 - -**外部读者文档**（guidedoc / libdoc）：frontmatter 由各自子技能定义。无特殊说明：`draft` = 待 review，`current` = 当前有效，`outdated` = 代码已变更待同步。 +**外部读者文档**（cs-doc-tutorial / cs-doc-api）：frontmatter 由各自子技能定义。无特殊说明：`draft` = 待 review，`current` = 当前有效，`outdated` = 代码已变更待同步。 **写作约束**：子技能提字段时优先写"额外字段"或"阶段状态变化"，不重复展开整套通用字段。 @@ -116,7 +109,7 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： - 是 feature 工作流的唯一执行清单 - 由 `cs-feat-design` 在 draft design 成型后先生成 `steps` + `checks`，供 `cs-feat-design-review` 和用户 review；用户确认后随 design 一起进入实现 -- `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-arch / cs-req backfill 检索到） +- `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-req / cs-domain backfill 检索到） `steps` 的粒度是 **编排-计算分离维度的切片策略**——按"先编排骨架、后计算节点、最后持久化与测试"写（最简 Workflow 先行 → 逐个节点填充），**不下沉到 file:line / 函数级**。具体改哪个文件由 implement 阶段决定。 @@ -181,26 +174,23 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 **feature-acceptance** 收尾按顺序判断： -1. `cs-learn`：沉淀经验 -2. `cs-decide`：长期约束 / 选型 -3. `cs-guide`：开发者 / 用户指南 -4. `cs-libdoc`：公开 API 参考 -5. `cs-docs-neat`：阶段 / 里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 -6. `scoped-commit` +1. `cs-keep`：沉淀坑点 / 技巧 / 长期约束 / 选型 +2. `cs-doc-tutorial`：开发者 / 用户指南 +3. `cs-doc-api`：公开 API 参考 +4. `cs-docs-neat`：阶段 / 里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 +5. `scoped-commit` **issue-fix** 收尾按顺序判断： -1. `cs-learn`：坑点 -2. `cs-decide`：暴露的长期约束 -3. `cs-docs-neat`：修复暴露了文档、agent 入口或记忆不一致时做全局整理 -4. `scoped-commit` +1. `cs-keep`：沉淀坑点或暴露的长期约束 +2. `cs-docs-neat`：修复暴露了文档、agent 入口或记忆不一致时做全局整理 +3. `scoped-commit` -**feature-ff** 收尾按顺序判断（比标准 acceptance 短，没有 architecture / req 回写动作）： +**feature-ff** 收尾按顺序判断（比标准 acceptance 短，没有 req 回写动作）： -1. `cs-learn`：动手过程暴露的坑 -2. `cs-decide`：动手过程拍板的长期约束 -3. `cs-docs-neat`：快速改动影响 README/docs 或 agent 入口时同步 -4. `scoped-commit` +1. `cs-keep`：动手过程暴露的坑或拍板的长期约束 +2. `cs-docs-neat`：快速改动影响 README/docs 或 agent 入口时同步 +3. `scoped-commit` **roadmap** 收尾按顺序判断： @@ -215,7 +205,7 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 acceptance / issue-fix 走完后把本次产物提交为一个 commit： -- **范围**：本次工作改到的代码 + 相关 spec 文档 + 本次实际更新过的架构 doc + 本次实际更新过的 roadmap items.yaml / 主文档 +- **范围**：本次工作改到的代码 + 相关 spec 文档 + 本次实际更新过的 CONTEXT.md / ADR / req doc + 本次实际更新过的 roadmap items.yaml / 主文档 - **不该进**：和本次工作无关的顺手修改；属于"下次另起 feature / issue"的扩大范围 - **提交前确认**：用户没明确同意不要 `git commit` - **commit message**：一句话说清"做了什么"，不贴 spec 目录路径 @@ -228,30 +218,22 @@ acceptance / issue-fix 走完后把本次产物提交为一个 commit： feature-design / issue-analyze / issue-fix 动手前到 `.codestable/compound/` 搜已有沉淀： -- 总是先搜 `architecture/` 和 `compound/` -- 在 `compound/` 用 `doc_type` 过滤（learning / trick / decision / explore） -- 搜到的结果只作参考输入，不盲目套用——可能已 `outdated` 或不适合当前上下文 -- 搜到和当前方向冲突的 decision → **必须**正面回应"为什么仍然这么做"或调整方向 - -子技能只补本阶段查询命令。完整搜索语法看 `.codestable/reference/tools.md`。 +- 总是先搜 `requirements/CONTEXT.md`、`requirements/adrs/`、`compound/` +- `compound/` 直接 `grep -r "关键词" .codestable/compound/`（纯 markdown，无 schema） +- 搜到的结果只作参考输入，不盲目套用——可能已过时或不适合当前上下文 +- 搜到和当前方向冲突的决策类沉淀 → **必须**正面回应"为什么仍然这么做"或调整方向 --- -## 6. 归档类子技能共享守护规则 +## 6. cs-keep 守护规则 -`cs-learn` / `cs-trick` / `cs-decide` / `cs-explore` 共享下面这组规则。子技能正文只写特有反模式，通用看这里： +`cs-keep` 写 compound 时遵守： -1. **只增不删**——已归档除非被明确取代（`status=superseded`）否则不删；理由丢失成本极高 -2. **宁缺毋滥**——用户说不出理由的节直接省略，不要 AI 编造 -3. **不替用户写实质内容**——AI 负责起草结构和串联语言，实质结论必须来自用户或可追溯的代码证据 -4. **attention.md 检查**——写完后若沉淀暴露出"每次启动都该知道"的一两行硬约束，提示用户用 `cs-note` 追加到 `.codestable/attention.md`；不要直接改外部 AI 入口 -5. **起草前先查重叠**——动手写前用 `search-yaml.py --query` 查语义相近的旧文档。命中就把候选列给用户在三条路径里选： - - **更新已有**（默认优先）：沿用原文件名和原创建日期，**不新建**；frontmatter 补 `updated: YYYY-MM-DD`；超出小修在文末加"YYYY-MM-DD 更新"简述 - - **supersede**：旧文档保留原文，`status: superseded` + `superseded-by: {新文件名}`，正文顶部加 `**[已取代]** 见 {新 slug}`；新文档 frontmatter 带 `supersedes: {旧文件名}` - - **确实是不同主题**：新建，文末"相关文档"列出已有那条说明区别 -6. **识别用户意图是"改已有"还是"记新的"**——用户说"改 / 更新 / 修订 / 补充 {某条}"、明确指向某条旧文档、或话题高度重合时默认走"更新已有"，不要闷头新建。分不清就问。 - -各子技能只认自己的 `doc_type`，不读写别家产物。 +1. **宁缺毋滥**——用户说不出理由的内容直接省略，不要 AI 编造 +2. **不替用户写实质内容**——AI 负责起草结构和串联语言，实质结论必须来自用户或可追溯的代码证据 +3. **attention.md 检查**——写完若沉淀暴露出"每次启动都该知道"的一两行硬约束，提示用户用 `cs-note` 追加到 `.codestable/attention.md` +4. **起草前先 grep 查重叠**——`grep -r "关键词" .codestable/compound/`。命中相近旧文档就问用户：更新已有 / 新写一份。默认优先更新已有，沿用原文件名，文末加"YYYY-MM-DD 更新"。 +5. **识别用户意图是"改已有"还是"记新的"**——用户说"改 / 更新 / 补充 {某条}"或话题高度重合时默认走"更新已有"，不要闷头新建。分不清就问。 --- diff --git a/cs-onboard/reference/system-overview.md b/cs-onboard/reference/system-overview.md index e8bca82..d6c9cda 100644 --- a/cs-onboard/reference/system-overview.md +++ b/cs-onboard/reference/system-overview.md @@ -25,10 +25,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 **沉淀**——把做事过程产生的知识存下来,下次遇到同类问题直接复用: -- `cs-learn` — 回顾"做 X 时踩了 Y 这个坑" -- `cs-trick` — 处方"以后做 X 就这样做" -- `cs-decide` — 规定"全项目今后都按 X 来" -- `cs-explore` — 存档"调查了 X 问题,看到代码里是这样的" +- `cs-keep` — 把坑点 / 技巧 / 决策 / 调研沉淀到 `.codestable/compound/`，纯 markdown，grep 检索 - `cs-note` — 把一两行启动必读的项目注意事项追加到 `.codestable/attention.md` **讨论层**——想法还模糊时的统一入口,不直接产出设计或代码: @@ -39,13 +36,13 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 - `cs-onboard` — 把新仓库接入 CodeStable 目录结构 - `cs-req` — 起草或刷新 `.codestable/requirements/` 下的需求文档——系统的能力愿景层，覆盖过去/现在/未来 -- `cs-arch` — 架构相关一站式:起草新架构文档 / 刷新已有文档 / 做架构体检(含 design 自洽 / design↔代码一致 / architecture 目录多份文档间一致)。architecture 只记现状 +- `cs-domain` — 领域模型一站式：CONTEXT.md 术语维护 + ADR 决策记录（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑管理 - `cs-roadmap` — 把一块装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单,作为后续多次 feature 流程的种子和排期依据;独立于需求 / 架构档案 - `cs-roadmap-review` — roadmap 人工确认前的只读规划审查 gate - `cs-roadmap-impl-goal` — 把已确认 roadmap 编排成可直接运行的 goal,逐个 feature 衔接 design / impl / review / QA / accept - `cs-feat-design-review` — feature design 人工确认前的只读方案审查 gate -- `cs-guide` — 写给外部读者的开发者指南 / 用户指南 -- `cs-libdoc` — 为库的公开 API 逐条目生成参考文档 +- `cs-doc-tutorial` — 写给外部读者的开发者指南 / 用户指南（任务导向） +- `cs-doc-api` — 为公开 API 逐条目生成参考文档（从源码反推） - `cs-docs-neat` — 阶段 / 里程碑收尾时，全局整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，做反膨胀、补漏和冲突修正 - `codestable-maintainer` — 维护 CodeStable 自身技能库 / harness / verifier / installed copy（源仓分支验证 + main-only 同步） @@ -62,45 +59,28 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 | BUG / 异常 / 文档错误 | `cs-issue` | | 代码优化 / 重构 / 重写(行为不变) | `cs-refactor` | | 合并前代码评审 / "code review" / 准备 PR / merge | `cs-code-review` | -| 摸代码、提问调研 | `cs-explore` | +| 摸代码、提问调研 / 踩坑回顾 / 技术选型沉淀 / 可复用模式 | `cs-keep` | | 补 / 更新需求文档 | `cs-req` | -| 补 / 更新 / 检查架构文档 | `cs-arch` | +| 拍板技术决策 / 加术语 / 项目要分子系统 | `cs-domain` | | 大需求拆解 / 排期规划 | `cs-roadmap` | | roadmap 人审前规划审查 | `cs-roadmap-review` | | 推进已有 roadmap / 执行整个 roadmap | `cs-roadmap-impl-goal` | | feature design 人审前方案审查 | `cs-feat-design-review` | -| 技术选型 / 约束 / 规约 | `cs-decide` | -| 踩坑回顾、经验总结 | `cs-learn` | -| 可复用的编程模式、库用法 | `cs-trick` | -| 开发者指南 / 用户指南 | `cs-guide` | -| 库 API 参考 | `cs-libdoc` | +| 开发者指南 / 用户指南 | `cs-doc-tutorial` | +| 库 API 参考 | `cs-doc-api` | | 阶段收尾 / 整理文档 / 同步 agent 入口 / 新人交接 | `cs-docs-neat` | 完整的操作手册、退出条件、和其他工作流的关系,各子技能里讲。 -## 沉淀类四个子技能如何区分 - -learning / trick / decision / explore 都是存档文档类型,区别在记录内容的性质: - -- 回顾某次做 X 时发现了 Y —— `cs-learn`(产出 `doc_type: learning`) -- 以后做 X 就这样做的处方 —— `cs-trick`(产出 `doc_type: trick`) -- 全项目今后都得遵守的规定 —— `cs-decide`(产出 `doc_type: decision`) -- 调查了一个问题,留份证据 —— `cs-explore`(产出 `doc_type: explore`) - -四者共用 `.codestable/compound/` 目录,靠 frontmatter 的 `doc_type` 字段和文件名中间的类型段(`YYYY-MM-DD-{doc_type}-{slug}.md`)区分。每个子技能只认自己的 `doc_type`,不读写别家产物——**"A 和 B 有什么不同"这种判断由本节负责,子技能里不再重复**。 - -`cs-docs-neat` 不新增沉淀文档类型。它是收尾整理器：发现该沉淀的知识时，仍然使用 learning / trick / decision / explore 这些既有 doc_type；同时同步 README/docs、`CLAUDE.md` / `AGENTS.md` 和外部 agent 记忆。 - - ## 愿景档案 vs 结构档案 vs 规划档案 vs 单次动作 四类文档各管一段时间尺度,不要混: - **愿景档案**(requirements)——描述"用户需要什么、系统提供什么能力来满足"。`status` 区分三个时间深度：`draft`（未来愿景）、`current`（现在的能力）、`outdated`（过去的痕迹）。draft req 可独立于实现存在——先把愿景定下来，后续 roadmap 排期和 design 实现才有稳定对齐基准 -- **结构档案**(architecture)——描述"系统现在用什么结构实现"。只记现状,默认在 feature-acceptance 时跟着代码同步;必要时由 cs-arch 主动刷新。**不写"未来会加什么层"** -- **规划档案**(roadmap)——描述"接下来打算怎么分步实现"。独立于愿景和结构档案,改动不牵连 requirements / architecture。所有条目 done / dropped 后 roadmap 进入 `completed` 状态,作为历史档案留存 -- **单次动作**(feature / issue / refactor)——本次要做的一件具体事情的 spec。动作走完后,相关沉淀提炼进愿景档案、结构档案和沉淀类文档 +- **领域档案**(CONTEXT.md / adrs/)——描述"项目用什么术语、为什么做出这些结构性决策"。术语跟着 capability 引入；ADR 严格 3 判据，不每个决定都记。cs-domain 维护 +- **规划档案**(roadmap)——描述"接下来打算怎么分步实现"。独立于愿景和领域档案,改动不牵连 requirements。所有条目 done / dropped 后 roadmap 进入 `completed` 状态,作为历史档案留存 +- **单次动作**(feature / issue / refactor)——本次要做的一件具体事情的 spec。动作走完后,相关沉淀提炼进愿景档案、结构档案和 compound 用户说"我想要一个 X 系统"这种大需求,先走 roadmap 拆成若干子 feature,再一条一条走 feature 流程。直接起 feature 会变成巨型 design 塞不下、拆了又没有追踪抓手。 @@ -116,14 +96,14 @@ AI 最常见的问题是一口气铺几百行代码才让人看——等发现 ## 进一步参考 -- `.codestable/reference/shared-conventions.md` — 目录结构、YAML frontmatter 口径、`{slug}-checklist.yaml` 生命周期、收尾 commit 约定、归档类共享规则 -- `.codestable/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法 +- `.codestable/reference/shared-conventions.md` — 目录结构、YAML frontmatter 口径、`{slug}-checklist.yaml` 生命周期、收尾 commit 约定、cs-keep 守护规则 +- `.codestable/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法（compound 不用这俩，直接 grep） - `.codestable/reference/maintainer-notes.md` — 断点恢复、新增子工作流的登记 -目录结构(requirements/、architecture/、roadmap/、features/、issues/、compound/、tools/、reference/)的权威定义在 `shared-conventions.md`。要改目录先改那里——方法是改 `cs-onboard/reference/shared-conventions.md` 这个模板,新项目 onboard 时会带上新版本。 +目录结构(requirements/、roadmap/、features/、issues/、compound/、tools/、reference/)的权威定义在 `shared-conventions.md`。要改目录先改那里——方法是改 `cs-onboard/reference/shared-conventions.md` 这个模板,新项目 onboard 时会带上新版本。 ## 相关 - `.codestable/attention.md` — CodeStable 技能启动必读的项目注意事项 -- `.codestable/architecture/ARCHITECTURE.md` — 项目架构总入口 +- `.codestable/requirements/CONTEXT.md` — 项目领域术语表（cs-domain，lazy 创建） diff --git a/cs-onboard/reference/tools.md b/cs-onboard/reference/tools.md index 75587e0..cf7b842 100644 --- a/cs-onboard/reference/tools.md +++ b/cs-onboard/reference/tools.md @@ -20,7 +20,7 @@ python3 .codestable/tools/search-yaml.py --dir {目录} [--filter key=value]... - `key=value`：字段精确匹配（大小写不敏感） - `key~=value`：字符串字段子串匹配；列表字段元素包含匹配 -- `key=a|b|c` / `key~=a|b|c`：同一字段多个候选值，候选之间是 OR；在 PowerShell / Bash 中请给整个 filter 加引号，例如 `--filter "doc_type=decision|explore|learning"` +- `key=a|b|c` / `key~=a|b|c`：同一字段多个候选值，候选之间是 OR；在 PowerShell / Bash 中请给整个 filter 加引号，例如 `--filter "status=approved|draft"` ### 排序语法 @@ -30,57 +30,39 @@ python3 .codestable/tools/search-yaml.py --dir {目录} [--filter key=value]... ### 常用命令 -沉淀类文档统一在 `.codestable/compound/`，用 `doc_type` 字段区分四个子技能的产物，内部还有各自的细分字段： +`search-yaml.py` 用于扫**带 frontmatter 的产物**——feature spec / issue spec / requirements / adrs / guides / library-docs。 + +`.codestable/compound/` 由 `cs-keep` 写纯 markdown（无 frontmatter），**不用 search-yaml**，直接 grep： ```bash -# 按 doc_type 筛选 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter "doc_type=decision|explore|learning" --filter status=active -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter status=active -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter status=active -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --filter status=active +grep -r "关键词" .codestable/compound/ +grep -rl "prisma" .codestable/compound/ # 只列文件名 +ls -lt .codestable/compound/ | head # 看最近沉淀 +``` -# doc_type + 子技能内部细分字段 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=pitfall -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter category=constraint -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter type=pattern -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --filter type=question - -# 按 tag（列表元素包含匹配） -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter tags~=prisma - -# 全文搜索 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --query "shadow database" - -# 按领域/框架/语言筛选 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter area=frontend -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter framework~=vue -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter language=typescript +带 frontmatter 的目录用 search-yaml： +```bash # 搜索 feature 方案 doc python3 .codestable/tools/search-yaml.py --dir .codestable/features --filter doc_type=feature-design --filter status=approved -# 输出控制 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter status=active --full -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter tags~=llm --json - # 按时间排序 -python3 .codestable/tools/search-yaml.py --dir .codestable/compound --sort-by date --order desc # 最近归档的在前 -python3 .codestable/tools/search-yaml.py --dir .codestable/library-docs --sort-by last_reviewed --order asc # 最久没 review 的在前（找陈旧文档） -python3 .codestable/tools/search-yaml.py --dir .codestable/guides --filter status=current --sort-by last_reviewed --order asc +python .codestable/tools/search-yaml.py --dir .codestable/library-docs --sort-by last_reviewed --order asc # 最久没 review 的在前（找陈旧文档） +python .codestable/tools/search-yaml.py --dir .codestable/guides --filter status=current --sort-by last_reviewed --order asc + +# 输出控制 +python .codestable/tools/search-yaml.py --dir .codestable/features --filter status=approved --full +python .codestable/tools/search-yaml.py --dir .codestable/features --filter tags~=llm --json ``` ### 典型使用场景 | 场景 | 命令建议 | |---|---| -| feature-design 开始前查已有归档 | 搜 `.codestable/compound` 目录，按 `--query "{关键词}"` 全文搜；要分类看就加 `--filter "doc_type=learning\|trick\|decision\|explore"` | -| issue-analyze 根因分析前查历史 | 搜 `.codestable/compound` `--filter doc_type=learning --filter track=pitfall`、再搜 `--filter doc_type=trick --filter type=library`，按相关组件/框架过滤 | -| 归档落盘后查重叠 | 搜 `.codestable/compound --query "{关键词}" --json`，看有无语义重叠 | -| 新人了解项目规约 | `--dir .codestable/compound --filter doc_type=decision --filter status=active` | -| 按技术栈浏览技巧 | `--dir .codestable/compound --filter doc_type=trick --filter language={语言} --filter status=active` | +| feature-design 开始前查 compound 已有沉淀 | `grep -r "{关键词}" .codestable/compound/` | +| issue-analyze 根因分析前查历史 | `grep -rl "{关键词}" .codestable/compound/` 再人工挑相关的看 | +| cs-keep 落盘前查重叠 | `grep -rl "{关键词}" .codestable/compound/`，命中就先看那条决定更新还是新写 | | 找最久没 review 的库文档 / 指南 | `--dir {目录} --filter status=current --sort-by last_reviewed --order asc` | -| 看最近沉淀了哪些经验 | `--dir .codestable/compound --filter doc_type=learning --sort-by date --order desc` | --- diff --git a/cs-onboard/tools/search-yaml.py b/cs-onboard/tools/search-yaml.py index 875c176..49115b3 100644 --- a/cs-onboard/tools/search-yaml.py +++ b/cs-onboard/tools/search-yaml.py @@ -12,31 +12,30 @@ Filter syntax (--filter flag, repeatable, AND logic): key~=a|b Substring/list match against any candidate value (OR) Usage examples: - # Search .codestable/compound (learning / trick / decision / explore docs share this dir) - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=pitfall - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter "doc_type=decision|explore|learning" - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter tags~=prisma - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=decision --filter status=active --full + # Search feature specs by status + python .codestable/tools/search-yaml.py --dir .codestable/features --filter doc_type=feature-design --filter status=approved - # Full-text search in body + frontmatter values - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --query "shadow database" + # Filter by tag (list element match) and full-text search body + frontmatter values + python .codestable/tools/search-yaml.py --dir .codestable/features --filter tags~=prisma + python .codestable/tools/search-yaml.py --dir .codestable/features --query "shadow database" # JSON output for AI agent consumption - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=learning --filter track=knowledge --json + python .codestable/tools/search-yaml.py --dir .codestable/issues --filter status=open --json # Sort by a frontmatter date field (works on any ISO-8601 date string, YAML date, or sortable value) - python3 .codestable/tools/search-yaml.py --dir .codestable/library-docs --sort-by last_reviewed --order asc # oldest first (stalest) - python3 .codestable/tools/search-yaml.py --dir .codestable/compound --sort-by date --order desc # newest first + python .codestable/tools/search-yaml.py --dir .codestable/library-docs --sort-by last_reviewed --order asc # oldest first (stalest) + + # NOTE: .codestable/compound/ is plain markdown (no frontmatter) — use grep instead: + # grep -r "keyword" .codestable/compound/ # Works on any yaml-frontmatter markdown directory - python3 .codestable/tools/search-yaml.py --dir docs/decisions --filter status=accepted - python3 .codestable/tools/search-yaml.py --dir content/posts --filter tags~=python --query "asyncio" + python .codestable/tools/search-yaml.py --dir docs/decisions --filter status=accepted + python .codestable/tools/search-yaml.py --dir content/posts --filter tags~=python --query "asyncio" """ import argparse import json import sys -from datetime import date, datetime from pathlib import Path try: @@ -151,7 +150,7 @@ class Filter: raise argparse.ArgumentTypeError( f"Invalid filter expression {raw!r}. " "Use 'key=value' for exact match or 'key~=value' for substring/list-contains match. " - "Use pipes for OR values, e.g. 'doc_type=decision|explore|learning'." + "Use pipes for OR values, e.g. 'status=approved|draft'." ) def matches(self, meta: dict) -> bool: @@ -256,13 +255,7 @@ def print_json(results: list[dict], full: bool) -> None: if not full and len(body) > 400: body = body[:400] + "…" output.append({"file": doc["file"], "meta": doc["meta"], "body": body}) - print(json.dumps(output, ensure_ascii=False, indent=2, default=_json_default)) - - -def _json_default(value): - if isinstance(value, (date, datetime)): - return value.isoformat() - return str(value) + print(json.dumps(output, ensure_ascii=False, indent=2)) # --------------------------------------------------------------------------- diff --git a/cs-onboard/tools/validate-yaml.py b/cs-onboard/tools/validate-yaml.py index c8d1a85..8a8b022 100644 --- a/cs-onboard/tools/validate-yaml.py +++ b/cs-onboard/tools/validate-yaml.py @@ -12,19 +12,19 @@ no required external dependencies (falls back to builtin parser if PyYAML unavai Usage examples: # Validate all .md files under codestable/features - python3 codestable/tools/validate-yaml.py --dir codestable/features + python codestable/tools/validate-yaml.py --dir codestable/features # Validate a single file - python3 codestable/tools/validate-yaml.py --file codestable/features/2026-04-11-auth/auth-design.md + python codestable/tools/validate-yaml.py --file codestable/features/2026-04-11-auth/auth-design.md # Check that required fields exist in frontmatter - python3 codestable/tools/validate-yaml.py --dir codestable/features --require doc_type --require status + python codestable/tools/validate-yaml.py --dir codestable/features --require doc_type --require status # JSON output for programmatic consumption - python3 codestable/tools/validate-yaml.py --dir docs/api --json + python codestable/tools/validate-yaml.py --dir docs/api --json - # Validate the libdoc manifest - python3 codestable/tools/validate-yaml.py --file docs/api/manifest.yaml --yaml-only + # Validate the doc-api manifest + python codestable/tools/validate-yaml.py --file docs/api/manifest.yaml --yaml-only """ import argparse diff --git a/cs-refactor/reference/refusal-routing.md b/cs-refactor/reference/refusal-routing.md index bef3045..952725a 100644 --- a/cs-refactor/reference/refusal-routing.md +++ b/cs-refactor/reference/refusal-routing.md @@ -40,9 +40,8 @@ scan 开始前跑一遍 7 条前置检查。任一命中**中止 scan 给路由 **路由**： > 主要问题是跨模块的：{具体描述}。这不是单模块 refactor 能解决的，需要先走： -> 1. `cs-arch` 更新模块边界图 -> 2. `cs-decide` 记新依赖原则 -> 3. 回来拆成若干单模块 refactor 任务 +> 1. `cs-domain` 写一条 ADR 记新的模块边界和依赖原则 +> 2. 回来拆成若干单模块 refactor 任务 --- @@ -54,7 +53,7 @@ scan 开始前跑一遍 7 条前置检查。任一命中**中止 scan 给路由 **路由**： > 主要是风格口味（命名 / 引号 / 格式）。正确处理方式不是 refactor： -> 1. `cs-decide` 拍板风格规约 +> 1. `cs-keep` 拍板风格规约 > 2. ESLint / Prettier 加规则 > 3. 跑一次 `--fix` 自动修全项目 @@ -81,7 +80,7 @@ scan 开始前跑一遍 7 条前置检查。任一命中**中止 scan 给路由 **路由**： > 范围涉及 {N 个文件 / M 行} 超过单次 scan 上限。先做一件事再回来： -> - 模块内部本来就该拆分 → 先走 `cs-arch` +> - 模块内部本来就该拆分 → 先走 `cs-domain` 写一条 ADR 立模块边界 > - 范围可缩 → 和用户挑一个子集（"就看 {具体组件}"） --- diff --git a/cs-req/SKILL.md b/cs-req/SKILL.md index 69cb109..1987fe8 100644 --- a/cs-req/SKILL.md +++ b/cs-req/SKILL.md @@ -45,7 +45,7 @@ description: 维护 `.codestable/requirements/` 下的能力愿景文档。三 - 用户主动修订：能力演进了要刷新（`update`） - 用户主动起草愿景：还没排期的未来需求先落一份 `draft` req 把定位定下来 -不适用：要写"技术上怎么搭" → `cs-arch`；写单次 feature 方案 → `cs-feat-design`；拍板长期规约 → `cs-decide`；写外部"怎么用" → `cs-guide`；大需求拆几轮做 → `cs-roadmap`。 +不适用：拍板架构决策 / 加术语 → `cs-domain`；写单次 feature 方案 → `cs-feat-design`；操作性沉淀 → `cs-keep`；写外部"怎么用" → `cs-doc-tutorial`；大需求拆几轮做 → `cs-roadmap`。 --- @@ -199,7 +199,7 @@ tags: [] | 方向 | 关系 | |---|---| -| `cs-arch` 配合 | req 写"为什么要有"、architecture 写"怎么搭"；arch doc frontmatter 用 `implements: [req-slug]` 反向链 | +| `cs-domain` 配合 | req 写"为什么要有"、cs-domain 管 CONTEXT 术语 / 拍板 ADR；ADR frontmatter 可用 `relates_to: [requirements/{req-slug}]` 反向链 | | `cs-brainstorm` 可触发 | 磋商后愿景清晰时可触发 `draft` 模式起草愿景 req | | `cs-feat-design` 可写 | design 读已有 req 对齐用户故事和边界；新能力首次设计方案化时触发 `draft` 模式起草愿景 req | | `cs-feat-accept` 主路径 | 验收统一处理 req 落档：draft req 对应的能力实现完成触发 `update`（draft → current，保留愿景追加变更日志）；从未写过 req 的能力触发 `backfill`（直接落 current）；已有 current req 的能力改变触发 `update` 刷新 | diff --git a/cs-roadmap/SKILL.md b/cs-roadmap/SKILL.md index ee7ee17..55fa092 100644 --- a/cs-roadmap/SKILL.md +++ b/cs-roadmap/SKILL.md @@ -17,9 +17,9 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 三块**一起**作为这块大需求所有子 feature 的共同约束——每条子 feature 进 `cs-feat-design` 时，roadmap 第 2 块的接口契约就是它的**硬约束输入**（不能违反，要改先回 roadmap update）。 -**为什么 roadmap 承载架构方案不放进 `architecture/`**：`cs-arch` 守"只记现状不记计划"。前瞻性架构方案属于"还没落地、可能还会变"的事前规划，放进 architecture 会污染那份系统地图。等子 feature 真正落地，对应接口由 `cs-feat-accept` 提炼回 `architecture/`——roadmap 完成过渡使命后归档。 +**为什么 roadmap 不直接写 ADR**：ADR（`requirements/adrs/`）记的是"已经拍板的稳定结构性决策"，roadmap 记的是"还没落地、可能还会变"的前瞻性接口契约。等子 feature 真正落地、对应接口稳定后，由 `cs-feat-accept` 盘点出来的领域影响触发 `cs-domain` 写 ADR——roadmap 完成过渡使命后归档。 -**为什么单独一层**：requirements 记"要什么"（愿景）、architecture 记"怎么搭"（结构）、roadmap 记"怎么分步实现"（执行）。把执行规划塞进愿景或结构文档会把"要什么"和"打算怎么实现"混起来——查不到系统真实能力，计划改一下又得改两份文档。 +**为什么单独一层**：requirements 记"要什么 + 怎么定义术语 + 拍板了哪些决策"（愿景 + 领域），roadmap 记"怎么分步实现"（执行）。把执行规划塞进 requirements 会把"要什么"和"打算怎么实现"混起来。 **为什么文件夹不是单文件**：拆解过程会产生草稿 / 调研 / 方案对比 / 白板转述，塞一份 md 会乱又舍不得删。每个 roadmap 一个子目录，主文档对外口径，旁边 `drafts/` 随便堆。 @@ -38,7 +38,7 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 - 已有 roadmap 加新子 feature / 改依赖 / 调顺序 / 标废弃 - feature-design 发现要做的事实际是多个 feature 集合，先退回拆 -不适用：单 feature 能装下 → `cs-feat`；描述能力"是什么、边界" → `cs-req`；描述系统"结构怎么搭" → `cs-arch`；拍板长期规约 / 选型 → `cs-decide`。 +不适用：单 feature 能装下 → `cs-feat`；描述能力"是什么、边界" → `cs-req`；拍板长期规约 / 架构选型 / 加术语 → `cs-domain`；操作性沉淀 → `cs-keep`。 --- @@ -81,10 +81,10 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 ### Phase 2：读取材料 -**共同必读**：`.codestable/attention.md` + 用户素材 + `roadmap/` 其他 roadmap（防重复）+ `requirements/` 相关 req + `architecture/` 相关 doc。 +**共同必读**：`.codestable/attention.md` + 用户素材 + `roadmap/` 其他 roadmap（防重复）+ `requirements/` 相关 req + `requirements/CONTEXT.md` + `requirements/adrs/` 相关 ADR。 **按情况读**： -- 相关 compound 沉淀：`python .codestable/tools/search-yaml.py --dir .codestable/compound --query "{大需求关键词}"` +- 相关 compound 沉淀：`grep -r "{大需求关键词}" .codestable/compound/` - 已有相关 feature 方案 - 项目可用验证命令 / 已知基线：从 `.codestable/attention.md`、架构 doc、历史 acceptance、README / package scripts / CI 配置里找 build / typecheck / lint / test / e2e / 浏览器验证入口。roadmap 不直接跑完整命令，但要知道后续每条 feature 靠什么验证 @@ -240,7 +240,7 @@ feature-design 发现接口契约不合理 / 漏了 / 描述不准 → **回 `cs | 方向 | 关系 | |---|---| | `cs-req` 配合 | req 记"为什么有这个能力"、roadmap 记"打算怎么分步做出来"。大需求下可能多份 req；缺 req 提示用户先 `cs-req` | -| `cs-arch` 配合 | architecture 记现状、roadmap 记若干步。读 arch 理解现状但不改它 | +| `cs-domain` 配合 | adrs/ 记已拍板决策、roadmap 记前瞻接口契约。读 ADR 理解现状但不改它 | | `cs-feat` 下游 | 每条子 feature 是未来一次 feature 流程的种子；起头时 design frontmatter 带 `roadmap` / `roadmap_item` | | `cs-feat-accept` 回写方 | acceptance 自动改 items.yaml 为 `done`，本技能只定义格式不负责回写 | | `cs-roadmap-impl-goal` 下游 | 用户确认 roadmap 后，可把所有子 feature design 和后续 impl / review / QA / accept 编排成可恢复的 goal | diff --git a/cs-roadmap/reference.md b/cs-roadmap/reference.md index f8330c6..027a729 100644 --- a/cs-roadmap/reference.md +++ b/cs-roadmap/reference.md @@ -129,7 +129,7 @@ payload: { user_id: str, role: str, changed_at: ISO8601 } 起草 / 刷新过程中发现、本 roadmap 不处理的事情交给用户决定： -- `architecture/X.md` 对 Y 的描述已过时，建议另起 architecture update +- `requirements/adrs/NNN.md` 中的 Y 决策已过时，建议另起一条 ADR superseded - requirement-Z 的边界和本 roadmap 第 5 条冲突，建议先对齐 req ## 8. 变更日志（update 模式） diff --git a/cs-trick/SKILL.md b/cs-trick/SKILL.md deleted file mode 100644 index 309b52e..0000000 --- a/cs-trick/SKILL.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -name: cs-trick -description: 把可复用的编程模式 / 库用法 / 技术技巧整理成处方性参考库，三种类型 pattern / library / technique。触发：用户说"记录一个技巧"、"这个用法值得记"、"tricks"、"记录库用法"，或 design / analyze 阶段发现值得沉淀的技巧时推送。 ---- - -# cs-trick - -## 启动必读 - -开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 - -cs-trick 是面向问题的**处方性参考库**，回答：**要做 X，经过验证的正确做法是什么？** 不需要触发事件，任何时候发现值得沉淀的模式或用法都可以直接写。 - -典型内容：某个设计模式在这个项目的标准写法 / 某个库的核心 API 用法 + 已知坑 / 某类操作的命令配方。 - -> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。产物写入 `.codestable/compound/`，命名 `YYYY-MM-DD-trick-{slug}.md`，frontmatter 带 `doc_type: trick`。 - ---- - -## 三种类型 - -frontmatter 的 `type` 字段： - -| 类型 | 适用情境 | 示例 | -|---|---|---| -| `pattern` | 设计模式 / 架构模式 / 编程惯用法 | "用 Repository 模式隔离数据访问层"、"用 Builder 构造复杂配置" | -| `library` | 某个库 / 框架的用法 / 配置方式 / 常见坑 | "Prisma 事务的正确写法"、"Pinia store 的 action 错误处理" | -| `technique` | 具体操作技巧 / 工具用法 / 命令配方 | "用 jq 从 JSON 提取嵌套字段"、"git bisect 定位引入 bug 的提交" | - -查询用途：查"代码该怎么组织"→ pattern；"库 / 框架某 API 怎么用"→ library；"这类操作怎么做"→ technique。分不清选最接近的，`type` 不影响搜索可用性。 - ---- - -## 文档格式 - -frontmatter / 正文模板 / 长示例见同目录 `reference.md`。流程约束： - -- `type` 只允许 `pattern` / `library` / `technique` -- 示例优先用项目真实代码或命令 -- "何时不适用 / 已知坑 / 相关文档"是可选节，用户说"没什么"就省略 - ---- - -## 工作流阶段 - -### Phase 1：识别类型 - -最多两个问题： - -1. "这是关于模式 / 结构、某个库 / 框架的用法，还是操作技巧 / 命令？" → 确定 `type` -2. "一句话说：遇到什么情况时会用到它？" → 确定 `topic` - -用户描述已清楚就跳过直接进 Phase 1.5。 - -### Phase 1.5：查重叠与意图分流（必做） - -按 `shared-conventions.md` §6 第 5/6 条： - -- 含"改 / 更新 / 修订 / 补充 / 某条 trick"或指向某份旧文档 → 直接走**更新已有**，不进新建流程 -- 否则用搜索工具 `--query` 查一遍 `topic`，命中相近时把候选列给用户 - -**更新流程**：读旧文档 → 和用户对齐改哪几节 → 跳过 Phase 2 完整代码调查（被改的节涉及的代码要重读确认未失效）→ 起草 diff 给用户 review → 写回 + `updated: YYYY-MM-DD`。 - -### Phase 2：代码调查（必做不可跳过） - -技巧通过代码体现——**用户不贴代码不等于不需要看代码**。AI 必须主动调查代码仓。 - -为什么必做：没看代码就写出的"技巧"会停留在抽象层面，下次有人按这条找代码会找不到对应的真实例子，反而失去信心。 - -1. **根据 topic + type 搜索代码仓**——Grep 关键词（函数名 / 类名 / 库导入 / 模式特征）；搜相关文件；必要时语义搜索补充 -2. **读取关键文件**——技巧实际使用 / 实现的代码位置：`library` 类找 import 和调用处；`pattern` 类找结构性代码（接口定义 / 类继承 / 组合）；`technique` 类找操作步骤对应的脚本或配置 -3. **产出**——记下文件路径和关键代码片段。完全找不到（纯经验性技巧、外部工具用法）就在 Phase 3 起草时说明"本技巧暂无项目内代码实例" - -补充：用户附带文件 → 仍要搜一遍代码仓确认有没有其他使用点；搜索结果为空 → 可继续但必须在文档注明；找到的代码和用户描述矛盾 → 主动跟用户确认。 - -### Phase 3：提炼要点（一次一个问题） - -**结合 Phase 2 找到的代码**提问——不问用户已经能在代码看到的东西： - -1. "标准做法是什么？"（已看到实现的直接展示理解请用户确认） -2. "为什么这样做有效？有什么原理？" -3. "什么情况下不该用它？"（可选） -4. "踩过坑或要注意的？"（可选，library 重点问） -5. "代码片段或命令示例？"（已找到实际代码就跳过，直接用真实代码作为示例） - -用户说"没什么"或"跳过"就跳过，宁缺节也不用空话填充。 - -### Phase 4：起草 + 用户 review - -AI 一次性起草完整文档（YAML frontmatter + 正文）。示例代码优先用 Phase 2 找到的真实项目代码（可精简），别凭空编写。展示给用户。 - -### Phase 5：归档 - -- 新建：写入 `compound/YYYY-MM-DD-trick-{slug}.md`，frontmatter 带 `doc_type: trick` -- 更新：写回 Phase 1.5 定位的原文件 + `updated: YYYY-MM-DD` -- supersede：按 `shared-conventions.md` §6 第 5 条处理 - -### Phase 6：可发现性检查 - -写完若发现一两行"每次 CodeStable 技能启动都该知道"的项目硬约束，提示用户用 `cs-note` 追加到 `.codestable/attention.md`。不要自作主张改 attention，也不要写外部 AI 入口。 - ---- - -## 搜索工具 - -> 完整语法见 `.codestable/reference/tools.md`。 - -```bash -# 按类型 + 框架筛选 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter type=library --filter framework~={库名} - -# 按技术栈浏览 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --filter language=typescript --filter status=active - -# 归档后查重叠 - -python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=trick --query "{关键词}" --json -``` - ---- - -## 守护规则 - -> 归档类共享规则见 `shared-conventions.md` 第 6 节。本技能特有： - -1. **只归档已验证的做法**——"也许应该这样做"不归档；必须用户或 AI 确认过有效 -2. **必须调查代码仓**——Phase 2 不可跳过。示例代码优先用项目真实代码不凭空编写 -3. **不替用户写原理**——用户说不清"为什么有效"就写"原理待补充"，不编造 -4. **示例优先于描述**——能用代码说清楚就用代码 -5. **只认自己的 doc_type**——只读写 `doc_type: trick` diff --git a/cs-trick/reference.md b/cs-trick/reference.md deleted file mode 100644 index 20e9d1e..0000000 --- a/cs-trick/reference.md +++ /dev/null @@ -1,65 +0,0 @@ -# tricks 参考模板 - -本文件提供 `cs-trick` 使用的技巧文档模板和示例。 - -## 1. frontmatter - -```yaml ---- -doc_type: trick -type: pattern | library | technique -date: YYYY-MM-DD -slug: {英文描述，连字符分隔} -topic: {一句话描述这条技巧解决什么问题} -language: {可选} -framework: {可选} -tags: [] -status: active | superseded -superseded-by: {可选} ---- -``` - -文件名：`.codestable/compound/YYYY-MM-DD-trick-{slug}.md`。 - -## 2. 正文模板 - -```markdown -## 适用场景 - -## 做法 - -## 为什么有效 - -## 示例 - -## 何时不适用 - -## 已知坑 - -## 相关文档 -``` - -`何时不适用`、`已知坑`、`相关文档` 都是可选节。 - -## 3. pattern 示例 - -```markdown ---- -doc_type: trick -type: pattern -date: 2026-04-11 -slug: repository-pattern-data-access -topic: 用 Repository 模式把数据访问逻辑和业务逻辑分开，方便单测和未来替换 ORM -language: typescript -tags: [repository, orm, testability, architecture] -status: active ---- - -## 适用场景 - -业务层代码直接调用 ORM，导致单测难写且切换 ORM 成本高。 - -## 做法 - -为每个聚合根创建 Repository 接口与实现，业务层只依赖接口，不直接导入 ORM。 -``` \ No newline at end of file diff --git a/cs/SKILL.md b/cs/SKILL.md index 3755542..3580f4e 100644 --- a/cs/SKILL.md +++ b/cs/SKILL.md @@ -35,19 +35,18 @@ description: CodeStable 工作流根入口，介绍体系全貌并把诉求路 ## 体系一图速读（用户没具体诉求 / 让你介绍时讲这个） -CodeStable 把开发活动建模成 **9 个实体 + 4 个流程**，所有产物聚在 `.codestable/`： +CodeStable 把开发活动建模成 **8 个实体 + 4 个流程**，所有产物聚在 `.codestable/`： ``` .codestable/ -├── requirements/ 需求实体（"为什么要有这个能力"，只记现状） -├── architecture/ 架构实体（"系统现在长什么样"，只记现状） +├── requirements/ 需求 + 领域模型（VISION + capability + CONTEXT.md + adrs/） ├── roadmap/ 规划层（roadmap / roadmap-review / goal 执行包） ├── goals/ 目标实体（限定起点/终点，自主迭代 + subagent 功能验收） ├── features/ 新增能力 spec 聚合根（design / design-review / impl / review / qa / accept） ├── issues/ 修 bug spec 聚合根（report / analyze / fix） ├── refactors/ 重构 spec 聚合根（beta） ├── audits/ 审计实体（主动扫描发现清单，不定修） -└── compound/ 知识沉淀（learning / trick / decision / explore） +└── compound/ 知识沉淀（cs-keep 写自由 markdown，grep 检索） ``` **四条流程**： @@ -57,9 +56,9 @@ CodeStable 把开发活动建模成 **9 个实体 + 4 个流程**，所有产物 - **修 bug**：`cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` - **重构**（beta）：`cs-refactor` / `cs-refactor-ff` -**横切**：commit 前走 `cs-code-review` 独立评审；发现"值得记下来" → `cs-learn` / `cs-trick` / `cs-decide` / `cs-explore` 沉淀到 `compound/`。 +**横切**：commit 前走 `cs-code-review` 独立评审；流程跑完发现"值得记下来" → `cs-keep` 沉淀到 `compound/`（纯 markdown，grep 检索）。 -**核心理念**：编排的是软件本身的生命周期（需求、架构、特性、bug、决策），不是 Agent。人在环——程序员对整体把控负责，AI 是高效执行体。 +**核心理念**：编排的是软件本身的生命周期（需求、领域模型、特性、bug、决策），不是 Agent。人在环——程序员对整体把控负责，AI 是高效执行体。 > 项目已 onboard 的话更详细总览看 `.codestable/reference/system-overview.md`。 @@ -102,22 +101,19 @@ L2/L3 需 owner 审批/选择/授权/接受风险时，子流程先按 `.codesta | 新功能 / "加个 X" / "实现 XX" | `cs-feat`（路由 design / ff / impl / accept） | | BUG / 异常 / 报错 / "这里不对" / "文档错了" | `cs-issue`（路由 report / analyze / fix） | | 代码优化 / 重构 / 重写（行为不变） | `cs-refactor` / `cs-refactor-ff` | -| 摸代码 / "X 是怎么实现的" / 提问调研 | `cs-explore` | | 审查系统 / 扫描 bug / 审计代码 / "有哪些问题" / "哪里可以优化" | `cs-audit`（主动扫描发现，只列清单不定修） | | 补 / 更新需求文档 | `cs-req` | -| 补 / 更新 / 检查架构文档 / "刷新架构 doc" / "做架构体检" | `cs-arch` | +| 拍板技术决策 / 加领域术语 / 项目要分子系统 | `cs-domain` | | 大需求拆解 / "我想要一个 X 系统" / 排期规划 / 模块拆分 + 接口契约 | `cs-roadmap` | | roadmap 人工确认前的规划审查 / "review 这个 roadmap" | `cs-roadmap-review` | | 推进已有 roadmap / 执行整个 roadmap / "继续 roadmap" / "用 goal 稳步推进 roadmap" | `cs-roadmap-impl-goal` | | feature design 人工确认前的方案审查 / "review 这个 design" | `cs-feat-design-review` | | 合并前审一下 / "code review" / "代码评审" / 准备 PR / merge | `cs-code-review`（对当前 diff 做独立评审，质量门禁） | -| CodeStable 自身技能 / harness / verifier / installed copy 更新 | `codestable-maintainer`（源码分支验证；真实 `~/.claude/skills` 只从 `origin/main` 同步） | -| 技术选型 / 长期约束 / 编码规约 | `cs-decide` | -| 踩坑回顾 / 经验总结 / "值得记下来" | `cs-learn` | -| 可复用编程模式 / 库用法 / "以后做 X 就该这样" | `cs-trick` | +| 术语 / 领域模型 / 架构决策 (ADR) / "这块属于哪个 context" | `cs-domain` | +| 摸代码调研 / 踩坑回顾 / 技术选型 / 长期约束 / 编码规约 / 可复用模式 / 库用法 / "值得记下来" | `cs-keep` | | 一两行的项目注意事项 / 编译特殊设置 / 命令陷阱 / "记到 attention.md" | `cs-note` | -| 开发者指南 / 用户指南 | `cs-guide` | -| 库 API 参考 | `cs-libdoc` | +| 开发者指南 / 用户指南 | `cs-doc-tutorial` | +| 库 API 参考 | `cs-doc-api` | | 阶段收尾 / 整理文档 / 同步 `CLAUDE.md` 或 `AGENTS.md` / 新人交接 | `cs-docs-neat` | | 用户在 feature / issue 流程中间问"下一步" | 路由到对应入口（`cs-feat` / `cs-issue`），让该入口判断当前阶段 | @@ -174,18 +170,12 @@ L2/L3 需 owner 审批/选择/授权/接受风险时，子流程先按 `.codesta 扫描看到 `features/` 或 `issues/` 下已有相关目录 → 提一句"看到 `features/2026-04-22-xxx/` 已经存在，是接着做这个吗？" 让用户确认续作还是开新的。 -### 沉淀类技能的细分 +### 沉淀类两个入口 -判别口诀： +- 写到 `.codestable/compound/` 一份独立 markdown（坑点 / 技巧 / 决策 / 调研，靠 grep 检索）→ `cs-keep` +- 一两行常驻提示"CodeStable 技能每次启动都得知道 X"（写到 `.codestable/attention.md`）→ `cs-note` -- 回顾"做 X 时踩了 Y" → `cs-learn` -- 处方"以后做 X 就这样做" → `cs-trick` -- 规定"全项目今后都按 X 来" → `cs-decide` -- 调查"X 现在是什么样" → `cs-explore` -- 一两行常驻提示"CodeStable 技能每次启动都得知道 X" → `cs-note`（写到 `.codestable/attention.md`） -- 阶段收尾后全局检查 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆是否同步 → `cs-docs-neat` - -判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档 / 常驻提示} 哪一种？" +判不出问用户："这个是要写一份独立文档（cs-keep），还是一两行启动必读（cs-note）？" --- @@ -221,7 +211,7 @@ L2/L3 需 owner 审批/选择/授权/接受风险时，子流程先按 `.codesta ## 不做的事 - **不读写 `.codestable/` 下的内容产物**——这些是子技能的事 -- **不替子技能做决策**——不在本技能做 brainstorm 分诊，不判 cs-arch 走哪个模式 +- **不替子技能做决策**——不在本技能做 brainstorm 分诊，不替 cs-domain 判断要不要写 ADR - **不一次推荐多个技能**——每次只指一条路；两个独立诉求分两轮 - **不重复体系总览细节**——`.codestable/reference/system-overview.md` 才是权威完整版 - **不绕过 `cs-onboard`**——仓库没接入就先 onboard