mirror of
https://github.com/codestable/CodeStable.git
synced 2026-09-19 09:03:09 +08:00
Merge origin/main (上游 refactor) into feat/merge-task-codereview-gates
吸收上游 74f1aa3 重构：compound 四件套合一 cs-keep、cs-libdoc→cs-doc-api、
cs-guide→cs-doc-tutorial、删 cs-arch 立 cs-domain、compound 改纯 markdown。
保留我们的 PR 工作：cs-code-review review↔gate、cs-goal、gate 工具链、
worktree feat/fix/refactor 命名、brainstorm/report-language；cs-task 保持删除。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
dafang
+190
-7
@@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow
|
||||
|
||||
<p>
|
||||
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
|
||||
<img src="https://img.shields.io/badge/cs--skills-35-6366F1?style=flat-square" alt="CodeStable Skills"/>
|
||||
<img src="https://img.shields.io/badge/cs--skills-27-6366F1?style=flat-square" alt="CodeStable Skills"/>
|
||||
<img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
|
||||
</p>
|
||||
|
||||
@@ -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
|
||||
|
||||
<table>
|
||||
<tr><th>Group</th><th>Skill</th><th>Purpose</th></tr>
|
||||
<tr><td><b>Root entry</b></td><td><code>cs</code></td><td>Unified entry — introduces the system and routes open-ended intents to the right cs-* skill. Call it when you don't know which one fits</td></tr>
|
||||
<tr><td><b>Onboard</b></td><td><code>cs-onboard</code></td><td>Bring CodeStable into a new repo or one with scattered docs</td></tr>
|
||||
<tr><td rowspan="2"><b>Requirement & domain</b></td><td><code>cs-req</code></td><td>Curate / accumulate capability vision docs</td></tr>
|
||||
<tr><td><code>cs-domain</code></td><td>Maintain <code>requirements/CONTEXT.md</code> glossary + <code>requirements/adrs/</code> architecture decisions (3-criteria gate + Nygard 4 sections) + single/multi context topology</td></tr>
|
||||
<tr><td><b>Roadmap</b></td><td><code>cs-roadmap</code></td><td>Up-front planning for a big chunk of work: high-level design + interface contracts + sub-feature breakdown</td></tr>
|
||||
<tr><td><b>Discussion entry</b></td><td><code>cs-brainstorm</code></td><td>Triage when ideas are still fuzzy: route to design / continue in a feature / hand off to roadmap</td></tr>
|
||||
<tr><td><b>Goal</b></td><td><code>cs-goal</code></td><td>Bounded start/end: write a start report, let AI iterate autonomously, with subagent functional acceptance before completion</td></tr>
|
||||
<tr><td rowspan="6"><b>Feature flow</b></td><td><code>cs-feat</code></td><td>Sub-flow entry for new features</td></tr>
|
||||
<tr><td><code>cs-feat-design</code></td><td>Draft <code>{slug}-design.md</code> as the single input for what follows</td></tr>
|
||||
<tr><td><code>cs-feat-impl</code></td><td>Code in the order the design lays out</td></tr>
|
||||
<tr><td><code>cs-code-review</code></td><td>Cross-cutting read-only code review gate before commit; produces <code>{slug}-review.md</code></td></tr>
|
||||
<tr><td><code>cs-feat-accept</code></td><td>Verify implementation against the design layer by layer; close the loop</td></tr>
|
||||
<tr><td><code>cs-feat-ff</code></td><td>Ultra-light lane: no design, no phases, AI just does it</td></tr>
|
||||
<tr><td rowspan="4"><b>Issue flow</b></td><td><code>cs-issue</code></td><td>Sub-flow entry for issue fixing</td></tr>
|
||||
<tr><td><code>cs-issue-report</code></td><td>Turn the problem in your head into a reproducible, traceable report</td></tr>
|
||||
<tr><td><code>cs-issue-analyze</code></td><td>Find root cause, assess fix risk, propose options</td></tr>
|
||||
<tr><td><code>cs-issue-fix</code></td><td>Targeted fix + verification + write fix-note</td></tr>
|
||||
<tr><td rowspan="2"><b>Refactor flow</b></td><td><code>cs-refactor</code></td><td>(beta) Main refactor flow</td></tr>
|
||||
<tr><td><code>cs-refactor-ff</code></td><td>(beta) Light refactor lane</td></tr>
|
||||
<tr><td><b>Knowledge sink</b></td><td><code>cs-keep</code></td><td>Sink pitfalls / tricks / decisions / exploration into <code>compound/</code> as plain markdown, searched via grep</td></tr>
|
||||
<tr><td rowspan="2"><b>Outward docs</b></td><td><code>cs-doc-tutorial</code></td><td>Outward-facing dev / user guides (task-oriented: how to use X to do Y)</td></tr>
|
||||
<tr><td><code>cs-doc-api</code></td><td>API reference reverse-engineered from source (entry-by-entry, parts lookup)</td></tr>
|
||||
</table>
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
<p>
|
||||
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
|
||||
<img src="https://img.shields.io/badge/cs--skills-35-6366F1?style=flat-square" alt="CodeStable Skills"/>
|
||||
<img src="https://img.shields.io/badge/cs--skills-27-6366F1?style=flat-square" alt="CodeStable Skills"/>
|
||||
<img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
|
||||
</p>
|
||||
|
||||
@@ -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 顺着软件编码的真实流程来设计，把开发活动建模成
|
||||
|
||||
## 技能总览
|
||||
|
||||
<table>
|
||||
<tr><th>分组</th><th>技能</th><th>用途</th></tr>
|
||||
<tr><td><b>根入口</b></td><td><code>cs</code></td><td>统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它</td></tr>
|
||||
<tr><td rowspan="1"><b>接入</b></td><td><code>cs-onboard</code></td><td>把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库</td></tr>
|
||||
<tr><td rowspan="2"><b>需求 & 领域</b></td><td><code>cs-req</code></td><td>整理 / 沉淀能力愿景 doc</td></tr>
|
||||
<tr><td><code>cs-domain</code></td><td>维护 <code>requirements/CONTEXT.md</code> 术语表 + <code>requirements/adrs/</code> 架构决策（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑</td></tr>
|
||||
<tr><td><b>路线图</b></td><td><code>cs-roadmap</code></td><td>承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单</td></tr>
|
||||
<tr><td><b>讨论入口</b></td><td><code>cs-brainstorm</code></td><td>想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap</td></tr>
|
||||
<tr><td><b>目标</b></td><td><code>cs-goal</code></td><td>限定起点/终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收</td></tr>
|
||||
<tr><td rowspan="6"><b>特性流程</b></td><td><code>cs-feat</code></td><td>新特性子流程入口</td></tr>
|
||||
<tr><td><code>cs-feat-design</code></td><td>起草 <code>{slug}-design.md</code> 作为后续唯一输入</td></tr>
|
||||
<tr><td><code>cs-feat-impl</code></td><td>按 design 的推进顺序写代码</td></tr>
|
||||
<tr><td><code>cs-code-review</code></td><td>实现完成后、commit 前的横切只读代码审查 gate，产 <code>{slug}-review.md</code></td></tr>
|
||||
<tr><td><code>cs-feat-accept</code></td><td>逐层对照 design 核对实现，做完整验收闭环</td></tr>
|
||||
<tr><td><code>cs-feat-ff</code></td><td>超轻量通道：不写 design、不分阶段，让 AI 直接做</td></tr>
|
||||
<tr><td rowspan="4"><b>问题流程</b></td><td><code>cs-issue</code></td><td>问题修复子流程入口</td></tr>
|
||||
<tr><td><code>cs-issue-report</code></td><td>把脑子里的问题落成可复现、可追溯的 report</td></tr>
|
||||
<tr><td><code>cs-issue-analyze</code></td><td>找根因、评估修复风险、给方案</td></tr>
|
||||
<tr><td><code>cs-issue-fix</code></td><td>定点修复 + 验证 + 写 fix-note</td></tr>
|
||||
<tr><td rowspan="2"><b>重构流程</b></td><td><code>cs-refactor</code></td><td>(beta) 重构主流程</td></tr>
|
||||
<tr><td><code>cs-refactor-ff</code></td><td>(beta) 轻量重构通道</td></tr>
|
||||
<tr><td><b>知识沉淀</b></td><td><code>cs-keep</code></td><td>坑点 / 技巧 / 决策 / 调研沉淀到 <code>compound/</code>，纯 markdown，grep 检索</td></tr>
|
||||
<tr><td rowspan="2"><b>对外文档</b></td><td><code>cs-doc-tutorial</code></td><td>对外的开发者指南 / 用户指南（任务导向，怎么用 X 做 Y）</td></tr>
|
||||
<tr><td><code>cs-doc-api</code></td><td>从源码反推的 API 参考（逐条目，给读者查零件）</td></tr>
|
||||
</table>
|
||||
|
||||
完整技能目录见 [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)。
|
||||
|
||||
---
|
||||
|
||||
@@ -15,6 +15,7 @@ Browser Bridge 是一个独立技能。它只说明自己的安装方式、命
|
||||
|
||||
- Python 依赖和 Chrome 扩展已经安装。
|
||||
- `python <skill-dir>/scripts/browser.py tabs` 能看到浏览器 tab。
|
||||
- 频繁执行命令时，先启动常驻 master，避免每次 CLI 调用都等待扩展重连。
|
||||
|
||||
## 架构
|
||||
|
||||
@@ -52,6 +53,22 @@ pip install bs4 simple-websocket-server bottle requests
|
||||
|
||||
下面的 `<skill-dir>` 指包含本 `SKILL.md` 的目录。
|
||||
|
||||
### 推荐：启动常驻 master
|
||||
|
||||
如果直接反复调用 `browser.py exec ...`，每个短命 CLI 进程都可能重新启动 bridge server，并等待 Chrome 扩展重连，通常会多出数秒冷启动时间。频繁操作浏览器时，先单独启动：
|
||||
|
||||
```bash
|
||||
python <skill-dir>/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 <skill-dir>/scripts/browser.py exec --no-monitor "document.title"
|
||||
```
|
||||
|
||||
### exec: 在浏览器里执行 JavaScript
|
||||
|
||||
这是最常用的主命令。直接写 JavaScript 查询或操作 DOM。系统会捕获返回值、DOM 变化和执行期间出现的短暂文本，例如 toast、通知、loading 文案。
|
||||
|
||||
@@ -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()
|
||||
@@ -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(); }});',
|
||||
|
||||
@@ -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`
|
||||
- 发现问题就顺手改代码或文档
|
||||
- 只说"这里不太对"不给证据位置
|
||||
- 建议过于抽象（"优化一下架构"）
|
||||
- 从一个目标无限扩展到全仓库审计
|
||||
@@ -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 "{模块关键词}"
|
||||
```
|
||||
+6
-6
@@ -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/` — 架构偏离类发现对照源
|
||||
|
||||
@@ -124,5 +124,5 @@ status: open
|
||||
### 架构偏离
|
||||
- [ ] 分层泄漏：上层直接调下层实现细节、绕过中间层
|
||||
- [ ] 模块隐式耦合：跨模块直接 import 内部文件（非公开 API）
|
||||
- [ ] 与 `.codestable/architecture/` 记录不一致
|
||||
- [ ] 与 `.codestable/requirements/adrs/` 已拍板决策不一致
|
||||
- [ ] 约定违背：命名 / 目录结构 / 错误处理模式与项目约定不符
|
||||
|
||||
+11
-1
@@ -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：已经够清楚
|
||||
|
||||
@@ -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`
|
||||
@@ -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 作为开发和生产构建工具。
|
||||
```
|
||||
@@ -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
|
||||
- 源码接口不存在却在文档写了——以源码为事实源不编造
|
||||
@@ -1,6 +1,6 @@
|
||||
# libdoc 参考模板
|
||||
# doc-api 参考模板
|
||||
|
||||
本文件提供 `cs-libdoc` 使用的 manifest、条目文档模板和源码提取清单。
|
||||
本文件提供 `cs-doc-api` 使用的 manifest、条目文档模板和源码提取清单。
|
||||
|
||||
## 1. `manifest.yaml` 格式
|
||||
|
||||
@@ -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 是任务教程 |
|
||||
|
||||
---
|
||||
|
||||
@@ -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 分级完
|
||||
@@ -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
|
||||
@@ -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. 后续建议
|
||||
|
||||
`后续建议` 节写一句话提示用户接下来可能的方向（下一步由用户自己决定，本节不枚举候选技能）。用户说"不用"就跳过。
|
||||
+26
-32
@@ -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`。
|
||||
|
||||
@@ -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，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长
|
||||
|
||||
|
||||
@@ -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 提示
|
||||
|
||||
|
||||
+12
-15
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 / 用户
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -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/` — 方案设计阶段需要查的领域术语与拍板决策
|
||||
|
||||
@@ -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`（涉及能力边界时读）
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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。
|
||||
|
||||
|
||||
+1
-1
@@ -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/` — 根因分析时可能要查的领域术语与拍板决策
|
||||
|
||||
@@ -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/`。
|
||||
@@ -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`
|
||||
@@ -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. 示例
|
||||
|
||||
完整示例可按仓库需要逐步补充；当前技能正文只保留流程，不再内嵌长示例。
|
||||
+12
-12
@@ -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 看到这一节是有意义的）
|
||||
- 注释行 `<!-- cs-note managed -->` 是本技能的识别锚——找不到就在文件末尾插入整块结构
|
||||
- **整段长度软上限 ~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 不再兼容这些外部入口
|
||||
- 默默新增分节——分节是写死的，新增要先和用户讨论
|
||||
- 看到一条就连带把其他几条也写进去——一次一条
|
||||
|
||||
+10
-11
@@ -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` — 架构总入口骨架
|
||||
|
||||
+1
-20
@@ -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` 追加。
|
||||
|
||||
|
||||
@@ -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 里删掉。
|
||||
|
||||
@@ -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. **识别用户意图是"改已有"还是"记新的"**——用户说"改 / 更新 / 补充 {某条}"或话题高度重合时默认走"更新已有"，不要闷头新建。分不清就问。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 创建）
|
||||
|
||||
@@ -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` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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))
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 立模块边界
|
||||
> - 范围可缩 → 和用户挑一个子集（"就看 {具体组件}"）
|
||||
|
||||
---
|
||||
|
||||
+2
-2
@@ -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` 刷新 |
|
||||
|
||||
+6
-6
@@ -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 |
|
||||
|
||||
@@ -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 模式）
|
||||
|
||||
@@ -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`
|
||||
@@ -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。
|
||||
```
|
||||
+15
-25
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user