From f45122dafbc38bcdc7f8a96204b71c806f366c0a Mon Sep 17 00:00:00 2001 From: zhuyongxin Date: Wed, 20 May 2026 11:39:30 +0800 Subject: [PATCH] Reorganize workspace and archive skill artifacts --- .agents/skills/diagnose/SKILL.md | 117 +++ .../diagnose/scripts/hitl-loop.template.sh | 41 + .agents/skills/grill-with-docs/ADR-FORMAT.md | 47 + .../skills/grill-with-docs/CONTEXT-FORMAT.md | 77 ++ .agents/skills/grill-with-docs/SKILL.md | 88 ++ .agents/skills/sm-flow/SKILL.md | 132 +++ .../sm-flow/references/archive-rules.md | 106 +++ .../skills/sm-flow/references/fallbacks.md | 101 +++ .../sm-flow/references/phase-contracts.md | 199 +++++ .../skills/sm-flow/references/templates.md | 290 ++++++ .agents/skills/tdd/SKILL.md | 109 +++ .agents/skills/tdd/deep-modules.md | 33 + .agents/skills/tdd/interface-design.md | 31 + .agents/skills/tdd/mocking.md | 59 ++ .agents/skills/tdd/refactoring.md | 10 + .agents/skills/tdd/tests.md | 61 ++ .agents/skills/to-prd/SKILL.md | 76 ++ .agents/skills/zoom-out/SKILL.md | 7 + .gitignore | 5 +- CONTEXT.md | 6 + README.md | 40 +- devflow/glossary/CONTEXT.md | 41 + .../0001-directory-name-as-truth-source.md | 39 + .../knowledge-index-panel-prd.md | 57 ++ .../add-clear-filters-acceptance.md | 70 ++ .../add-clear-filters-alignment.md | 24 + .../add-clear-filters-clarifications.md | 18 + .../add-clear-filters-design.md | 24 + .../add-clear-filters-prd.md | 50 ++ .../add-clear-filters-research.md | 23 + .../add-clear-filters-tasks.md | 20 + .../add-year-filter-acceptance.md | 44 + .../add-year-filter-design.md | 29 + .../add-year-filter-prd.md | 50 ++ .../add-year-filter-research.md | 24 + .../add-year-filter-tasks.md | 20 + .../dev-flow-skill-evaluation.md | 116 +++ .../todo.md | 44 + knowledge-index.html | 298 +++++++ .../knowledge_20260417_Waza.html | 498 +++++++++++ .../knowledge_20260417_Waza.md | 339 +++++++ .../knowledge_20260518_mattpocock_skills.html | 825 ++++++++++++++++++ .../knowledge_20260518_mattpocock_skills.md | 440 ++++++++++ .../knowledge_20260519_CodeStable.html | 370 ++++++++ .../knowledge_20260519_CodeStable.md | 378 ++++++++ openspec/changes/add-year-filter/design.md | 31 + openspec/changes/add-year-filter/proposal.md | 26 + .../specs/knowledge-filtering/spec.md | 28 + openspec/changes/add-year-filter/tasks.md | 25 + .../2026-05-19-add-clear-filters/design.md | 46 + .../2026-05-19-add-clear-filters/proposal.md | 32 + .../specs/knowledge-filtering/spec.md | 33 + .../2026-05-19-add-clear-filters/tasks.md | 25 + .../knowledge-index-panel/.openspec.yaml | 2 + .../changes/knowledge-index-panel/design.md | 58 ++ .../changes/knowledge-index-panel/proposal.md | 28 + .../specs/knowledge-indexing/spec.md | 39 + .../specs/knowledge-linking/spec.md | 35 + .../specs/knowledge-search/spec.md | 39 + .../changes/knowledge-index-panel/tasks.md | 26 + scripts/update-knowledge-index.sh | 436 +++++++++ .../explore-essence-follow/latest-design.md | 270 ++++++ skill-workbench/docs/sm-flow/workflow.md | 383 ++++++++ .../generated-skills/skills/essence/SKILL.md | 259 ++++++ .../essence/references/essence-signals.md | 79 ++ .../generated-skills/skills/explore/SKILL.md | 87 ++ .../explore/references/analysis-methods.md | 98 +++ .../explore/references/flow-patterns.md | 173 ++++ .../explore/scripts/collect-structure.sh | 120 +++ .../generated-skills/skills/follow/SKILL.md | 101 +++ .../skills/follow/references/env-detect.md | 113 +++ .../generated-skills/sm-flow/SKILL.md | 132 +++ .../sm-flow/references/archive-rules.md | 106 +++ .../sm-flow/references/fallbacks.md | 101 +++ .../sm-flow/references/phase-contracts.md | 199 +++++ .../sm-flow/references/templates.md | 290 ++++++ .../2026-04-30-skills-v0.5.0-consolidation.md | 136 +++ .../0001-directory-name-as-truth-source.md | 39 + .../docs/agents/knowledge-index-panel-prd.md | 57 ++ skill-workbench/validation/skills-lock.json | 35 + .../validation/tmp2/lumina-essence-report.md | 216 +++++ .../tmp2/lumina-explore-report-optimized.md | 235 +++++ .../validation/tmp2/lumina-explore-report.md | 134 +++ 83 files changed, 9733 insertions(+), 15 deletions(-) create mode 100644 .agents/skills/diagnose/SKILL.md create mode 100644 .agents/skills/diagnose/scripts/hitl-loop.template.sh create mode 100644 .agents/skills/grill-with-docs/ADR-FORMAT.md create mode 100644 .agents/skills/grill-with-docs/CONTEXT-FORMAT.md create mode 100644 .agents/skills/grill-with-docs/SKILL.md create mode 100644 .agents/skills/sm-flow/SKILL.md create mode 100644 .agents/skills/sm-flow/references/archive-rules.md create mode 100644 .agents/skills/sm-flow/references/fallbacks.md create mode 100644 .agents/skills/sm-flow/references/phase-contracts.md create mode 100644 .agents/skills/sm-flow/references/templates.md create mode 100644 .agents/skills/tdd/SKILL.md create mode 100644 .agents/skills/tdd/deep-modules.md create mode 100644 .agents/skills/tdd/interface-design.md create mode 100644 .agents/skills/tdd/mocking.md create mode 100644 .agents/skills/tdd/refactoring.md create mode 100644 .agents/skills/tdd/tests.md create mode 100644 .agents/skills/to-prd/SKILL.md create mode 100644 .agents/skills/zoom-out/SKILL.md create mode 100644 CONTEXT.md create mode 100644 devflow/glossary/CONTEXT.md create mode 100644 devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md create mode 100644 devflow/projects/2026-05-18-knowledge-index-panel/knowledge-index-panel-prd.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-acceptance.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-alignment.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-clarifications.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-design.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-prd.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-research.md create mode 100644 devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-tasks.md create mode 100644 devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md create mode 100644 devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md create mode 100644 devflow/projects/2026-05-19-add-year-filter/add-year-filter-prd.md create mode 100644 devflow/projects/2026-05-19-add-year-filter/add-year-filter-research.md create mode 100644 devflow/projects/2026-05-19-add-year-filter/add-year-filter-tasks.md create mode 100644 devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md create mode 100644 devflow/projects/2026-05-19-dev-flow-skill-evaluation/todo.md create mode 100644 knowledge-index.html create mode 100644 knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.html create mode 100644 knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.md create mode 100644 knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.html create mode 100644 knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.md create mode 100644 knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.html create mode 100644 knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.md create mode 100644 openspec/changes/add-year-filter/design.md create mode 100644 openspec/changes/add-year-filter/proposal.md create mode 100644 openspec/changes/add-year-filter/specs/knowledge-filtering/spec.md create mode 100644 openspec/changes/add-year-filter/tasks.md create mode 100644 openspec/changes/archive/2026-05-19-add-clear-filters/design.md create mode 100644 openspec/changes/archive/2026-05-19-add-clear-filters/proposal.md create mode 100644 openspec/changes/archive/2026-05-19-add-clear-filters/specs/knowledge-filtering/spec.md create mode 100644 openspec/changes/archive/2026-05-19-add-clear-filters/tasks.md create mode 100644 openspec/changes/knowledge-index-panel/.openspec.yaml create mode 100644 openspec/changes/knowledge-index-panel/design.md create mode 100644 openspec/changes/knowledge-index-panel/proposal.md create mode 100644 openspec/changes/knowledge-index-panel/specs/knowledge-indexing/spec.md create mode 100644 openspec/changes/knowledge-index-panel/specs/knowledge-linking/spec.md create mode 100644 openspec/changes/knowledge-index-panel/specs/knowledge-search/spec.md create mode 100644 openspec/changes/knowledge-index-panel/tasks.md create mode 100644 scripts/update-knowledge-index.sh create mode 100644 skill-workbench/docs/explore-essence-follow/latest-design.md create mode 100644 skill-workbench/docs/sm-flow/workflow.md create mode 100644 skill-workbench/generated-skills/skills/essence/SKILL.md create mode 100644 skill-workbench/generated-skills/skills/essence/references/essence-signals.md create mode 100644 skill-workbench/generated-skills/skills/explore/SKILL.md create mode 100644 skill-workbench/generated-skills/skills/explore/references/analysis-methods.md create mode 100644 skill-workbench/generated-skills/skills/explore/references/flow-patterns.md create mode 100644 skill-workbench/generated-skills/skills/explore/scripts/collect-structure.sh create mode 100644 skill-workbench/generated-skills/skills/follow/SKILL.md create mode 100644 skill-workbench/generated-skills/skills/follow/references/env-detect.md create mode 100644 skill-workbench/generated-skills/sm-flow/SKILL.md create mode 100644 skill-workbench/generated-skills/sm-flow/references/archive-rules.md create mode 100644 skill-workbench/generated-skills/sm-flow/references/fallbacks.md create mode 100644 skill-workbench/generated-skills/sm-flow/references/phase-contracts.md create mode 100644 skill-workbench/generated-skills/sm-flow/references/templates.md create mode 100644 skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md create mode 100644 skill-workbench/history/docs/adr/0001-directory-name-as-truth-source.md create mode 100644 skill-workbench/history/docs/agents/knowledge-index-panel-prd.md create mode 100644 skill-workbench/validation/skills-lock.json create mode 100644 skill-workbench/validation/tmp2/lumina-essence-report.md create mode 100644 skill-workbench/validation/tmp2/lumina-explore-report-optimized.md create mode 100644 skill-workbench/validation/tmp2/lumina-explore-report.md diff --git a/.agents/skills/diagnose/SKILL.md b/.agents/skills/diagnose/SKILL.md new file mode 100644 index 0000000..ed55bda --- /dev/null +++ b/.agents/skills/diagnose/SKILL.md @@ -0,0 +1,117 @@ +--- +name: diagnose +description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression. +--- + +# Diagnose + +A discipline for hard bugs. Skip phases only when explicitly justified. + +When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. + +## Phase 1 — Build a feedback loop + +**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you. + +Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.** + +### Ways to construct one — try them in roughly this order + +1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e. +2. **Curl / HTTP script** against a running dev server. +3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot. +4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network. +5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation. +6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call. +7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode. +8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it. +9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs. +10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you. + +Build the right feedback loop, and the bug is 90% fixed. + +### Iterate on the loop itself + +Treat the loop as a product. Once you have _a_ loop, ask: + +- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.) +- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".) +- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.) + +A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower. + +### Non-deterministic bugs + +The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable. + +### When you genuinely cannot build a loop + +Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop. + +Do not proceed to Phase 2 until you have a loop you believe in. + +## Phase 2 — Reproduce + +Run the loop. Watch the bug appear. + +Confirm: + +- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix. +- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against). +- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it. + +Do not proceed until you reproduce the bug. + +## Phase 3 — Hypothesise + +Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea. + +Each hypothesis must be **falsifiable**: state the prediction it makes. + +> Format: "If is the cause, then will make the bug disappear / will make it worse." + +If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it. + +**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK. + +## Phase 4 — Instrument + +Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.** + +Tool preference: + +1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs. +2. **Targeted logs** at the boundaries that distinguish hypotheses. +3. Never "log everything and grep". + +**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die. + +**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second. + +## Phase 5 — Fix + regression test + +Write the regression test **before the fix** — but only if there is a **correct seam** for it. + +A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence. + +**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase. + +If a correct seam exists: + +1. Turn the minimised repro into a failing test at that seam. +2. Watch it fail. +3. Apply the fix. +4. Watch it pass. +5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario. + +## Phase 6 — Cleanup + post-mortem + +Required before declaring done: + +- [ ] Original repro no longer reproduces (re-run the Phase 1 loop) +- [ ] Regression test passes (or absence of seam is documented) +- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix) +- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location) +- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns + +**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started. diff --git a/.agents/skills/diagnose/scripts/hitl-loop.template.sh b/.agents/skills/diagnose/scripts/hitl-loop.template.sh new file mode 100644 index 0000000..40afc46 --- /dev/null +++ b/.agents/skills/diagnose/scripts/hitl-loop.template.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Human-in-the-loop reproduction loop. +# Copy this file, edit the steps below, and run it. +# The agent runs the script; the user follows prompts in their terminal. +# +# Usage: +# bash hitl-loop.template.sh +# +# Two helpers: +# step "" → show instruction, wait for Enter +# capture VAR "" → show question, read response into VAR +# +# At the end, captured values are printed as KEY=VALUE for the agent to parse. + +set -euo pipefail + +step() { + printf '\n>>> %s\n' "$1" + read -r -p " [Enter when done] " _ +} + +capture() { + local var="$1" question="$2" answer + printf '\n>>> %s\n' "$question" + read -r -p " > " answer + printf -v "$var" '%s' "$answer" +} + +# --- edit below --------------------------------------------------------- + +step "Open the app at http://localhost:3000 and sign in." + +capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)" + +capture ERROR_MSG "Paste the error message (or 'none'):" + +# --- edit above --------------------------------------------------------- + +printf '\n--- Captured ---\n' +printf 'ERRORED=%s\n' "$ERRORED" +printf 'ERROR_MSG=%s\n' "$ERROR_MSG" diff --git a/.agents/skills/grill-with-docs/ADR-FORMAT.md b/.agents/skills/grill-with-docs/ADR-FORMAT.md new file mode 100644 index 0000000..da7e78e --- /dev/null +++ b/.agents/skills/grill-with-docs/ADR-FORMAT.md @@ -0,0 +1,47 @@ +# ADR Format + +ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. + +Create the `docs/adr/` directory lazily — only when the first ADR is needed. + +## Template + +```md +# {Short title of the decision} + +{1-3 sentences: what's the context, what did we decide, and why.} +``` + +That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. + +## Optional sections + +Only include these when they add genuine value. Most ADRs won't need them. + +- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited +- **Considered Options** — only when the rejected alternatives are worth remembering +- **Consequences** — only when non-obvious downstream effects need to be called out + +## Numbering + +Scan `docs/adr/` for the highest existing number and increment by one. + +## When to offer an ADR + +All three of these must be true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing." + +### What qualifies + +- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres." +- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." +- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out. +- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s. +- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate. +- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract." +- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months. diff --git a/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md b/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md new file mode 100644 index 0000000..ddfa247 --- /dev/null +++ b/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md @@ -0,0 +1,77 @@ +# CONTEXT.md Format + +## Structure + +```md +# {Context Name} + +{One or two sentence description of what this context is and why it exists.} + +## Language + +**Order**: +{A concise description of the term} +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request + +**Customer**: +A person or organization that places orders. +_Avoid_: Client, buyer, account + +## Relationships + +- An **Order** produces one or more **Invoices** +- An **Invoice** belongs to exactly one **Customer** + +## Example dialogue + +> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?" +> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed." + +## Flagged ambiguities + +- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts. +``` + +## Rules + +- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. +- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution. +- **Keep definitions tight.** One sentence max. Define what it IS, not what it does. +- **Show relationships.** Use bold term names and express cardinality where obvious. +- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. +- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. +- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts. + +## Single vs multi-context repos + +**Single context (most repos):** One `CONTEXT.md` at the repo root. + +**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other: + +```md +# Context Map + +## Contexts + +- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders +- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments +- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping + +## Relationships + +- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking +- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices +- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money` +``` + +The skill infers which structure applies: + +- If `CONTEXT-MAP.md` exists, read it to find contexts +- If only a root `CONTEXT.md` exists, single context +- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved + +When multiple contexts exist, infer which one the current topic relates to. If unclear, ask. diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md new file mode 100644 index 0000000..5ea0aa9 --- /dev/null +++ b/.agents/skills/grill-with-docs/SKILL.md @@ -0,0 +1,88 @@ +--- +name: grill-with-docs +description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +--- + + + +Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time, waiting for feedback on each question before continuing. + +If a question can be answered by exploring the codebase, explore the codebase instead. + + + + + +## Domain awareness + +During codebase exploration, also look for existing documentation: + +### File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). + + diff --git a/.agents/skills/sm-flow/SKILL.md b/.agents/skills/sm-flow/SKILL.md new file mode 100644 index 0000000..d22e598 --- /dev/null +++ b/.agents/skills/sm-flow/SKILL.md @@ -0,0 +1,132 @@ +--- +name: sm-flow +description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。 +--- + +# SM Flow + +SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。 + +## 角色定位 + +你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。 + +## 真理源分层 + +- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。 +- `openspec/changes//` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。 +- 代码是实现结果：只能在执行真理源足够明确后修改。 +- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。 + +## 核心规则 + +- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。 +- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。 +- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。 +- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。 +- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。 +- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。 +- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。 +- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。 +- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。 +- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。 +- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。 +- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。 +- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。 +- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。 + +## 首次加载 + +执行前只读取当前任务需要的 reference 文件： + +- 需要逐阶段执行时，读取 `references/phase-contracts.md`。 +- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。 +- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。 +- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。 + +## 启动检查 + +1. 判断启动模式： + - 完整模式：用户提供粗略想法或初始 PRD。 + - Research 模式：用户已有 research，需要转成或修正 OpenSpec。 + - PRD 文件模式：用户提供已有 PRD 路径。 + - 指定阶段模式：用户要求从某个 Phase 恢复。 + - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。 +2. 如果缺少 `devflow/`，初始化： + - `devflow/projects/` + - `devflow/glossary/CONTEXT.md` + - `devflow/compound/` + - `devflow/reference/` +3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。 +4. 检查 OpenSpec 和子 skill 是否可用： + - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。 + - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。 +5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。 + +## 项目标识 + +整个流程使用同一个 slug： + +- 优先使用 OpenSpec change name。 +- 如果还没有 change name，则从功能标题生成 kebab-case slug。 +- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。 +- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。 + +## Devflow 产物分层 + +devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。 + +**必须产物**： + +- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。 +- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。 +- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。 +- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。 + +**按需产物**： + +- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。 +- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。 +- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。 +- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。 +- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。 +- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。 + +**规模分档**： + +- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。 +- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。 +- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。 + +## 阶段总览 + +1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。 +2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。 +3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。 +4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。 +5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。 +6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。 +7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。 +8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。 + +每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。 + +## 快速模式 + +快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留： + +- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。 +- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。 +- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。 +- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。 + +## 完成标准 + +一次流程只有在满足以下条件时才算完成： + +- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。 +- 实现或规划任务已经完成，且执行依据来自 OpenSpec。 +- 已运行验证，或明确记录未运行验证的原因。 +- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。 +- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。 + diff --git a/.agents/skills/sm-flow/references/archive-rules.md b/.agents/skills/sm-flow/references/archive-rules.md new file mode 100644 index 0000000..a013bfb --- /dev/null +++ b/.agents/skills/sm-flow/references/archive-rules.md @@ -0,0 +1,106 @@ +# 归档规则 + +Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。 + +## 目录规则 + +项目档案路径： + +```text +devflow/projects/YYYY-MM-DD-{slug}/ +``` + +默认创建以下必要文件： + +- `brief.md` +- `evidence.md` +- `decisions.md` +- `acceptance.md` + +按需创建以下扩展文件： + +- `prd.md` +- `research.md` +- `design.md` +- `tasks.md` +- `alignment.md` +- `adr/*.md` + +不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。 + +## 产物分档 + +| 分档 | 适用场景 | 必须文件 | 扩展文件 | +| --- | --- | --- | --- | +| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` | +| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound | +| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` | + +## 提取映射 + +| 来源 | 提取内容 | 写入位置 | +| --- | --- | --- | +| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` | +| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` | +| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 | +| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` | +| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` | +| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` | +| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` | +| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` | +| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` | + +## 验收记录规则 + +必须真实记录验证情况，并按类型分类： + +- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。 +- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。 +- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。 +- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。 + +记录要求： + +- 如果验证通过，记录命令/步骤和覆盖范围。 +- 如果验证失败，记录失败摘要和是否阻塞验收。 +- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。 + +## ADR 规则 + +同时满足以下条件时创建 ADR： + +1. 决策难以逆转。 +2. 缺少上下文会让未来维护者困惑。 +3. 决策来自真实权衡，而不是简单偏好。 + +项目内 ADR 存放于： + +```text +devflow/projects/YYYY-MM-DD-{slug}/adr/ +``` + +跨项目可复用决策或经验存放于： + +```text +devflow/compound/YYYY-MM-DD-decision-{slug}.md +``` + +## 归档确认 + +OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息： + +- Phase 4 可以建议 archive，但必须先询问用户。 +- 在用户确认前，不要执行 archive。 +- 如果用户暂不归档，在 acceptance 中记录原因或状态。 +- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。 + +## 归档交接 + +Phase 4 结束时告诉用户： + +- 创建或更新了哪些档案文件。 +- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。 +- 还剩哪些风险或后续事项。 +- 明确询问：是否现在 archive OpenSpec change？ + + diff --git a/.agents/skills/sm-flow/references/fallbacks.md b/.agents/skills/sm-flow/references/fallbacks.md new file mode 100644 index 0000000..64000fb --- /dev/null +++ b/.agents/skills/sm-flow/references/fallbacks.md @@ -0,0 +1,101 @@ +# Fallback 协议 + +当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。 + +## OpenSpec 提案 fallback + +1. 创建或识别 `openspec/changes/{slug}/`。 +2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。 +3. 写入 `proposal.md`，包含： + - 问题 + - 建议方案 + - 范围 + - 非目标 + - 来自 devflow 的上下文约束 + - 风险 +4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。 +5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。 +6. 只为外部可见行为或发生变化的需求编写 specs。 +7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。 + +## OpenSpec 修正 fallback + +当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时： + +1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。 +2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。 +3. 向用户汇报冲突和推荐修正。 +4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。 +5. 再同步更新 devflow 文档；不要只改 devflow。 + +## OpenSpec 执行 fallback + +仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。 + +1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。 +2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。 +3. 修改前先检查现有代码。 +4. 一次实现一个 OpenSpec task 的纵向切片。 +5. 用最窄但有效的命令验证每个切片。 +6. 只有验证通过或明确记录原因后，才更新 task 状态。 +7. 如果失败原因不确定，停止并进入 diagnose。 +8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。 + +## PRD fallback + +优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。 + +规则： + +- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。 +- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。 +- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。 + +## 文档化追问 fallback + +1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。 +2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。 +3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。 +4. 对 user-interview 问题，一次只问一个并等待用户确认。 +5. 术语确认后立即更新词汇表。 +6. 影响实现的澄清必须回写 OpenSpec。 +7. 只为难以逆转的真实权衡创建 ADR。 + +快速模式的最小问题： + +- 术语：这个概念应该使用哪个领域术语？证据是什么？ +- 边界：哪些内容明确不在范围内？是否需要用户确认？ +- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？ + +## 架构审计 fallback + +产出一份短架构审计： + +1. 画出输入 → 处理 → 输出。 +2. 列出相关模块和调用方。 +3. 识别耦合、数据所有权和生命周期风险。 +4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。 +5. 用不超过五句话总结最大风险。 +6. 如果影响实现，回写 OpenSpec design/tasks。 + +## Diagnose fallback + +1. 复现问题，或捕获准确失败信息。 +2. 最小化失败案例。 +3. 生成 3-5 个假设，并按可能性和验证成本排序。 +4. 修改代码前，先添加仪器化或定向检查。 +5. 判断根因属于实现问题还是 OpenSpec 规格问题。 +6. 如果是实现问题，修复被证明的最小原因。 +7. 如果是规格问题，先修正 OpenSpec，再继续 apply。 +8. 运行回归验证。 + +## TDD fallback + +使用纵向切片，不要水平批量写测试： + +1. 从 OpenSpec specs 中选择一个外部可见行为。 +2. 写一个失败测试。 +3. 实现刚好让测试通过的最小代码。 +4. 只在测试通过时重构。 +5. 对下一个 OpenSpec 行为重复以上步骤。 + diff --git a/.agents/skills/sm-flow/references/phase-contracts.md b/.agents/skills/sm-flow/references/phase-contracts.md new file mode 100644 index 0000000..0b5b7f6 --- /dev/null +++ b/.agents/skills/sm-flow/references/phase-contracts.md @@ -0,0 +1,199 @@ +# 阶段契约 + +本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。 + +## Phase 0 — 入口澄清 + +**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。 + +**动作**： +- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。 +- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。 +- 如果输入过于模糊，最多追加三轮聚焦问题。 +- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。 + +**退出条件**： +- 问题可以用 1-2 句话说清楚。 +- 期望结果可以用 1-2 句话说清楚。 +- 已列出已知影响代码或模块；如果未知，也明确标记。 +- 可以生成 OpenSpec change slug。 + +**输出**： +- 入口摘要。 +- 初步 slug。 +- devflow 规模分档：`micro` / `standard` / `complex`。 + +## Phase 0.5 — Devflow 上下文收集 + +**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。 + +**动作**： +- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。 +- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。 +- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。 +- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。 +- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。 + +**退出条件**： +- 已形成“OpenSpec 输入上下文摘要”。 +- 已列出相关 ADR 和不能违反的历史决策。 +- 已列出需要写入或修正 OpenSpec 的上下文点。 + +**输出**： +- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。 + +## Phase 1 — OpenSpec propose + +**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。 + +**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。 + +**动作**： +- 优先调用 `openspec-propose`。 +- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。 +- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec： + - proposal 写清为什么做、做什么、范围和非目标。 + - design 写入上下文约束、历史 ADR、关键技术决策。 + - specs 写成可验收的外部行为。 + - tasks 写成可执行的纵向切片。 +- 在承诺设计细节前，先检查相关仓库代码。 + +**退出条件**： +- `openspec/changes//proposal.md` 存在。 +- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。 +- 关键假设已显式记录在 OpenSpec 或 research 中。 + +**输出**： +- OpenSpec proposal、design、specs 和 task list。 + +**Human checkpoint**： +- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。 +- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。 + +## Phase 1.5 — PRD / OpenSpec 对齐 + +**进入条件**：Phase 1 已有 OpenSpec 产物。 + +**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。 + +**动作**： +- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。 +- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。 +- 检查 PRD、devflow 上下文和 OpenSpec 是否一致： + - OpenSpec 是否覆盖 PRD 的用户故事和验收预期。 + - OpenSpec 是否使用 glossary 中的正确术语。 + - OpenSpec 是否遵守相关 ADR。 + - specs 是否能表达可观察行为。 + - tasks 是否能驱动实现，而不是泛泛描述。 +- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。 + +**退出条件**： +- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。 +- OpenSpec 与 PRD/devflow 上下文没有已知冲突。 +- 所有已知冲突已修正或等待用户决策。 + +**输出**： +- `brief.md`，以及按需创建的 `prd.md`。 +- OpenSpec 对齐检查记录。 +- 必要的 OpenSpec 修正。 + +## Phase 2 — Human-in-the-loop 澄清 + +**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。 + +**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。 + +**动作**： +- 优先使用 `grill-with-docs`。 +- 先声明本阶段采用的澄清模式，并逐项标记： + - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。 + - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。 +- 至少覆盖三个维度：术语、边界、验收。 +- 一次只问一个 `user-interview` 问题。 +- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。 +- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。 +- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。 + +**退出条件**： +- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。 +- 所有 evidence-driven 结论已向用户汇报。 +- 所有 user-interview 决策已获得用户确认。 +- 影响实现的结论已回写 OpenSpec。 + +**输出**： +- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。 +- 更新后的 OpenSpec。 +- 更新后的词汇表和 ADR。 + +## Phase 2.5 — 架构审计 + +**进入条件**：Phase 2 已解决主要产品、领域和验收问题。 + +**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。 + +**动作**： +- 画出输入 → 处理 → 输出的模块链路。 +- 识别跨模块依赖、数据所有权、生命周期和耦合风险。 +- 检查是否与既有架构、ADR、OpenSpec design 冲突。 +- 用不超过五句话写出架构风险评估。 +- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。 + +**退出条件**： +- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。 +- OpenSpec design/tasks 已反映会影响实现的架构审计结论。 + +**输出**： +- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。 +- 必要的 OpenSpec design/tasks 修正。 + +**Human checkpoint**： +- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。 +- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。 + +## Phase 3 — OpenSpec apply + +**进入条件**： +- `openspec/changes//` 中 proposal/design/specs/tasks 已达到可执行状态。 +- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。 +- devflow 与 OpenSpec 没有未解决冲突。 + +**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。 + +**动作**： +- 优先调用 `openspec-apply-change`。 +- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。 +- 按 OpenSpec tasks 的纵向切片实现。 +- 当用户要求、行为复杂或回归风险高时使用 TDD。 +- 当测试失败、行为意外或原因不确定时使用 diagnose。 +- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。 +- 修改文件前遵守仓库指令，例如 `AGENTS.md`。 + +**退出条件**： +- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。 +- 已运行验证，或记录了未验证原因。 +- 已列出已知限制。 + +**输出**： +- 代码变更、必要测试和实现说明。 +- 更新后的 OpenSpec task 状态。 + +## Phase 4 — 回填 Devflow + +**进入条件**：实现或规划工作已经达到可交接状态。 + +**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。 + +**动作**： +- 遵循 `references/archive-rules.md`。 +- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。 +- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。 +- 如果本次流程产生可复用经验，写入 compound knowledge。 +- 询问用户是否要 archive OpenSpec change；不要默认执行归档。 + +**退出条件**： +- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。 +- 用户已被询问是否 archive OpenSpec change。 + +**输出**： +- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。 + diff --git a/.agents/skills/sm-flow/references/templates.md b/.agents/skills/sm-flow/references/templates.md new file mode 100644 index 0000000..e9b6885 --- /dev/null +++ b/.agents/skills/sm-flow/references/templates.md @@ -0,0 +1,290 @@ +# 模板 + +这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。 + +## Brief 模板 + +```markdown +# {标题} Brief + +## 背景 + +- 用户目标：{goal} +- 当前问题：{problem} +- 关联 OpenSpec：`openspec/changes/{slug}/` +- devflow 分档：micro | standard | complex + +## 范围 + +- 本次要做：{in scope} +- 本次不做：{out of scope} +- 影响区域：{modules/files if known} + +## OpenSpec 对齐 + +- proposal 覆盖状态：已覆盖 / 待修正 / 不适用 +- specs 覆盖状态：已覆盖 / 待修正 / 不适用 +- tasks 覆盖状态：已覆盖 / 待修正 / 不适用 +``` + +## Evidence 模板 + +```markdown +# {标题} Evidence + +## 证据 + +| 来源 | 证据 | 结论 | 是否已汇报 | +| --- | --- | --- | --- | +| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 | + +## Evidence-driven 结论 + +- 结论：{conclusion} + - 证据：{evidence} + - 风险：{risk if any} + - 用户确认：需要 / 不需要 / 已确认 +``` + +## Decisions 模板 + +```markdown +# {标题} Decisions + +## User-interview + +| 问题 | 用户回答 | 决策 | OpenSpec 回写 | +| --- | --- | --- | --- | +| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 | + +## 关键取舍 + +- 决策：{decision} + - 原因：{why} + - 影响：{impact} + - 风险接受：{accepted by whom/when} +``` + +## PRD 模板 + +```markdown +# {标题} PRD + +## 问题陈述 + +用用户视角描述问题。 + +## 解决方案 + +用用户视角描述预期解决方案。 + +## 用户故事 + +1. 作为{角色}，我希望{能力}，以便{收益}。 + +## 实现决策 + +- 决策：{decision} + - 原因：{why} + - 影响：{affected modules or behavior} + +## 测试决策 + +- 好测试应该通过{public interface}验证{observable behavior}。 +- 必须覆盖：{critical paths} +- 不测试：{explicit exclusions} + +## 非目标 + +- {excluded behavior} + +## 补充说明 + +- {open question or useful context} +``` + +## 词汇表模板 + +```markdown +# 上下文词汇表 + +## 术语 + +### {术语} + +- 定义：{precise definition} +- 使用场景：{feature/module/context} +- 备注：{ambiguities, synonyms, or rejected meanings} + +## 业务规则 + +- {rule}: {meaning and source} +``` + +## ADR 模板 + +```markdown +# ADR-{编号}: {决策标题} + +**状态**：提议中 | 已接受 | 已废弃 +**日期**：YYYY-MM-DD + +## 背景 + +是什么情况迫使我们做这个决策？ + +## 决策 + +我们选择了什么？ + +## 替代方案 + +| 方案 | 拒绝原因 | +| --- | --- | +| {option} | {reason} | + +## 后果 + +### 正面 + +- {benefit} + +### 负面 + +- {cost or risk} +``` + +## 技术调研模板 + +```markdown +# {标题} 技术调研 + +## 摘要 + +- 变更原因：{reason} +- 变更范围：{scope} +- 主要技术方案：{approach} + +## 源产物 + +- OpenSpec change: `openspec/changes/{slug}/` +- 关联 PRD: `prd.md` 或 `brief.md` + +## 关键发现 + +- {finding} + +## 假设 + +- {assumption and validation status} +``` + +## 设计模板 + +```markdown +# {标题} 设计 + +## 架构摘要 + +描述输入 → 处理 → 输出。 + +## 关键决策 + +- {decision}: {reason} + +## 模块地图 + +| 模块 | 职责 | 备注 | +| --- | --- | --- | +| {module} | {responsibility} | {notes} | + +## 架构审计 + +- 风险：{risk} +- 缓解：{mitigation} +``` + +## 任务模板 + +```markdown +# {标题} 任务 + +## 需求追踪 + +| 需求 | 状态 | 备注 | +| --- | --- | --- | +| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} | + +## 实现任务 + +- [ ] {task} +``` + +## 验收模板 + +```markdown +# {标题} 验收 + +## 结果 + +已接受 / 部分接受 / 未接受。 + +## 验证 + +### 静态验证 + +- 命令/检查：`{command or check}` +- 结果：{passed/failed/not run} +- 备注：{important output or reason not run} + +### 脚本验证 + +- 命令：`{command}` +- 结果：{passed/failed/not run} +- 备注：{important output or reason not run} + +### 浏览器/人工验证 + +- 步骤：{manual steps} +- 结果：{passed/failed/not run} +- 备注：{observations or reason not run} + +## 已完成范围 + +- {completed behavior} + +## 已知限制 + +- {limitation} + +## Bug 修复和诊断 + +- {bug}: {diagnosis summary and regression coverage} + +## 交接 + +- 下一步：{archive, deploy, review, or follow-up} +- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用} +``` + +## 复合知识模板 + +```markdown +# {标题} + +**类型**：learning | trick | decision | explore +**日期**：YYYY-MM-DD + +## 背景 + +这条经验来自哪里？ + +## 经验 + +未来代理应该复用什么经验？ + +## 适用性 + +什么时候适用？什么时候不适用？ +``` + diff --git a/.agents/skills/tdd/SKILL.md b/.agents/skills/tdd/SKILL.md new file mode 100644 index 0000000..7a98941 --- /dev/null +++ b/.agents/skills/tdd/SKILL.md @@ -0,0 +1,109 @@ +--- +name: tdd +description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +--- + +# Test-Driven Development + +## Philosophy + +**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. + +**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure. + +**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior. + +See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. + +## Anti-Pattern: Horizontal Slices + +**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code." + +This produces **crap tests**: + +- Tests written in bulk test _imagined_ behavior, not _actual_ behavior +- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior +- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine +- You outrun your headlights, committing to test structure before understanding the implementation + +**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it. + +``` +WRONG (horizontal): + RED: test1, test2, test3, test4, test5 + GREEN: impl1, impl2, impl3, impl4, impl5 + +RIGHT (vertical): + RED→GREEN: test1→impl1 + RED→GREEN: test2→impl2 + RED→GREEN: test3→impl3 + ... +``` + +## Workflow + +### 1. Planning + +When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. + +Before writing any code: + +- [ ] Confirm with user what interface changes are needed +- [ ] Confirm with user which behaviors to test (prioritize) +- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) +- [ ] Design interfaces for [testability](interface-design.md) +- [ ] List the behaviors to test (not implementation steps) +- [ ] Get user approval on the plan + +Ask: "What should the public interface look like? Which behaviors are most important to test?" + +**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case. + +### 2. Tracer Bullet + +Write ONE test that confirms ONE thing about the system: + +``` +RED: Write test for first behavior → test fails +GREEN: Write minimal code to pass → test passes +``` + +This is your tracer bullet - proves the path works end-to-end. + +### 3. Incremental Loop + +For each remaining behavior: + +``` +RED: Write next test → fails +GREEN: Minimal code to pass → passes +``` + +Rules: + +- One test at a time +- Only enough code to pass current test +- Don't anticipate future tests +- Keep tests focused on observable behavior + +### 4. Refactor + +After all tests pass, look for [refactor candidates](refactoring.md): + +- [ ] Extract duplication +- [ ] Deepen modules (move complexity behind simple interfaces) +- [ ] Apply SOLID principles where natural +- [ ] Consider what new code reveals about existing code +- [ ] Run tests after each refactor step + +**Never refactor while RED.** Get to GREEN first. + +## Checklist Per Cycle + +``` +[ ] Test describes behavior, not implementation +[ ] Test uses public interface only +[ ] Test would survive internal refactor +[ ] Code is minimal for this test +[ ] No speculative features added +``` diff --git a/.agents/skills/tdd/deep-modules.md b/.agents/skills/tdd/deep-modules.md new file mode 100644 index 0000000..0d9720c --- /dev/null +++ b/.agents/skills/tdd/deep-modules.md @@ -0,0 +1,33 @@ +# Deep Modules + +From "A Philosophy of Software Design": + +**Deep module** = small interface + lots of implementation + +``` +┌─────────────────────┐ +│ Small Interface │ ← Few methods, simple params +├─────────────────────┤ +│ │ +│ │ +│ Deep Implementation│ ← Complex logic hidden +│ │ +│ │ +└─────────────────────┘ +``` + +**Shallow module** = large interface + little implementation (avoid) + +``` +┌─────────────────────────────────┐ +│ Large Interface │ ← Many methods, complex params +├─────────────────────────────────┤ +│ Thin Implementation │ ← Just passes through +└─────────────────────────────────┘ +``` + +When designing interfaces, ask: + +- Can I reduce the number of methods? +- Can I simplify the parameters? +- Can I hide more complexity inside? diff --git a/.agents/skills/tdd/interface-design.md b/.agents/skills/tdd/interface-design.md new file mode 100644 index 0000000..a0a20ca --- /dev/null +++ b/.agents/skills/tdd/interface-design.md @@ -0,0 +1,31 @@ +# Interface Design for Testability + +Good interfaces make testing natural: + +1. **Accept dependencies, don't create them** + + ```typescript + // Testable + function processOrder(order, paymentGateway) {} + + // Hard to test + function processOrder(order) { + const gateway = new StripeGateway(); + } + ``` + +2. **Return results, don't produce side effects** + + ```typescript + // Testable + function calculateDiscount(cart): Discount {} + + // Hard to test + function applyDiscount(cart): void { + cart.total -= discount; + } + ``` + +3. **Small surface area** + - Fewer methods = fewer tests needed + - Fewer params = simpler test setup diff --git a/.agents/skills/tdd/mocking.md b/.agents/skills/tdd/mocking.md new file mode 100644 index 0000000..71cbfee --- /dev/null +++ b/.agents/skills/tdd/mocking.md @@ -0,0 +1,59 @@ +# When to Mock + +Mock at **system boundaries** only: + +- External APIs (payment, email, etc.) +- Databases (sometimes - prefer test DB) +- Time/randomness +- File system (sometimes) + +Don't mock: + +- Your own classes/modules +- Internal collaborators +- Anything you control + +## Designing for Mockability + +At system boundaries, design interfaces that are easy to mock: + +**1. Use dependency injection** + +Pass external dependencies in rather than creating them internally: + +```typescript +// Easy to mock +function processPayment(order, paymentClient) { + return paymentClient.charge(order.total); +} + +// Hard to mock +function processPayment(order) { + const client = new StripeClient(process.env.STRIPE_KEY); + return client.charge(order.total); +} +``` + +**2. Prefer SDK-style interfaces over generic fetchers** + +Create specific functions for each external operation instead of one generic function with conditional logic: + +```typescript +// GOOD: Each function is independently mockable +const api = { + getUser: (id) => fetch(`/users/${id}`), + getOrders: (userId) => fetch(`/users/${userId}/orders`), + createOrder: (data) => fetch('/orders', { method: 'POST', body: data }), +}; + +// BAD: Mocking requires conditional logic inside the mock +const api = { + fetch: (endpoint, options) => fetch(endpoint, options), +}; +``` + +The SDK approach means: +- Each mock returns one specific shape +- No conditional logic in test setup +- Easier to see which endpoints a test exercises +- Type safety per endpoint diff --git a/.agents/skills/tdd/refactoring.md b/.agents/skills/tdd/refactoring.md new file mode 100644 index 0000000..8a44439 --- /dev/null +++ b/.agents/skills/tdd/refactoring.md @@ -0,0 +1,10 @@ +# Refactor Candidates + +After TDD cycle, look for: + +- **Duplication** → Extract function/class +- **Long methods** → Break into private helpers (keep tests on public interface) +- **Shallow modules** → Combine or deepen +- **Feature envy** → Move logic to where data lives +- **Primitive obsession** → Introduce value objects +- **Existing code** the new code reveals as problematic diff --git a/.agents/skills/tdd/tests.md b/.agents/skills/tdd/tests.md new file mode 100644 index 0000000..ff22f80 --- /dev/null +++ b/.agents/skills/tdd/tests.md @@ -0,0 +1,61 @@ +# Good and Bad Tests + +## Good Tests + +**Integration-style**: Test through real interfaces, not mocks of internal parts. + +```typescript +// GOOD: Tests observable behavior +test("user can checkout with valid cart", async () => { + const cart = createCart(); + cart.add(product); + const result = await checkout(cart, paymentMethod); + expect(result.status).toBe("confirmed"); +}); +``` + +Characteristics: + +- Tests behavior users/callers care about +- Uses public API only +- Survives internal refactors +- Describes WHAT, not HOW +- One logical assertion per test + +## Bad Tests + +**Implementation-detail tests**: Coupled to internal structure. + +```typescript +// BAD: Tests implementation details +test("checkout calls paymentService.process", async () => { + const mockPayment = jest.mock(paymentService); + await checkout(cart, payment); + expect(mockPayment.process).toHaveBeenCalledWith(cart.total); +}); +``` + +Red flags: + +- Mocking internal collaborators +- Testing private methods +- Asserting on call counts/order +- Test breaks when refactoring without behavior change +- Test name describes HOW not WHAT +- Verifying through external means instead of interface + +```typescript +// BAD: Bypasses interface to verify +test("createUser saves to database", async () => { + await createUser({ name: "Alice" }); + const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]); + expect(row).toBeDefined(); +}); + +// GOOD: Verifies through interface +test("createUser makes user retrievable", async () => { + const user = await createUser({ name: "Alice" }); + const retrieved = await getUser(user.id); + expect(retrieved.name).toBe("Alice"); +}); +``` diff --git a/.agents/skills/to-prd/SKILL.md b/.agents/skills/to-prd/SKILL.md new file mode 100644 index 0000000..47a01d4 --- /dev/null +++ b/.agents/skills/to-prd/SKILL.md @@ -0,0 +1,76 @@ +--- +name: to-prd +description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context. +--- + +This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. + +The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. + +## Process + +1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. + +2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. + +A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. + +Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. + +3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. + + + +## Problem Statement + +The problem that the user is facing, from the user's perspective. + +## Solution + +The solution to the problem, from the user's perspective. + +## User Stories + +A LONG, numbered list of user stories. Each user story should be in the format of: + +1. As an , I want a , so that + + +1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending + + +This list of user stories should be extremely extensive and cover all aspects of the feature. + +## Implementation Decisions + +A list of implementation decisions that were made. This can include: + +- The modules that will be built/modified +- The interfaces of those modules that will be modified +- Technical clarifications from the developer +- Architectural decisions +- Schema changes +- API contracts +- Specific interactions + +Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. + +Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +## Testing Decisions + +A list of testing decisions that were made. Include: + +- A description of what makes a good test (only test external behavior, not implementation details) +- Which modules will be tested +- Prior art for the tests (i.e. similar types of tests in the codebase) + +## Out of Scope + +A description of the things that are out of scope for this PRD. + +## Further Notes + +Any further notes about the feature. + + diff --git a/.agents/skills/zoom-out/SKILL.md b/.agents/skills/zoom-out/SKILL.md new file mode 100644 index 0000000..1e7a5dc --- /dev/null +++ b/.agents/skills/zoom-out/SKILL.md @@ -0,0 +1,7 @@ +--- +name: zoom-out +description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. +disable-model-invocation: true +--- + +I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. diff --git a/.gitignore b/.gitignore index 316b38b..d09bf04 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ -project/\ndocs/\nsuperpowers/\n +skill-workbench/validation/project/ +superpowers/ +.claude/ +*.stackdump diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..2c3c1b0 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,6 @@ +# CONTEXT.md — github-learn + +> 本文件已迁移至 `devflow/glossary/CONTEXT.md`。 +> 根目录仅保留兼容性入口，避免旧流程或旧 skill 继续读取过期词汇表。 + +请以 `devflow/glossary/CONTEXT.md` 为准。 diff --git a/README.md b/README.md index ae51ad5..b134495 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,33 @@ -# Explore Skill Family +# github-learn -一组 Claude Code 学习型技能，帮助开发者系统性地理解和学习代码仓库或知识仓库。 +个人知识学习与 agent workflow 实验仓库。 -## 技能 +## 当前核心内容 -| 技能 | 用途 | 触发 | -|---|---|---| -| `/explore` | 项目级理解与上手路径 | 第一次接触项目，需要全貌认知 | -| `/essence` | 核心设计深潜与迁移 | 抓住最值得学的设计，拆解到可迁移 | -| `/follow` | 基于报告的引导式学习 | 已有分析结果，想边做边学 | +| 路径 | 作用 | +| --- | --- | +| `knowledge/entries/knowledge_YYYYMMDD_*/` | 知识条目源文件与渲染 HTML | +| `knowledge-index.html` | 知识索引页面，由 `scripts/update-knowledge-index.sh` 生成 | +| `scripts/` | 本仓库维护脚本 | +| `openspec/` | 当前 OpenSpec 变更工作区与归档 | +| `devflow/` | 人类可读项目档案、glossary、复合知识 | +| `.agents/skills/` | Codex/agent 使用的本地运行时 skills，当前重点是 `sm-flow` | +| `.claude/skills/` | Claude 版本 skills 与 OpenSpec skills | +| `skill-workbench/` | skill 创建、设计文档、历史文档与验证沙箱 | -## 使用 +## 上下文入口 -将 `skills/` 目录安装到 Claude Code 的 skills 目录下即可使用。 +- 领域词汇表真理源：`devflow/glossary/CONTEXT.md` +- 根目录 `CONTEXT.md` 仅保留兼容性重定向。 -工作流：`/explore` → 拿到线索 → `/essence` 深挖设计 → `/follow` 跟学。 +## 历史内容 -## 版本 - -v0.5.0 — 详细变更见 [changelog/](changelog/) +- `skill-workbench/generated-skills/sm-flow/`：本仓库新增的 `sm-flow` skill 源产物，只放可安装 skill 本体。 +- `skill-workbench/generated-skills/skills/`：早期 Explore Skill Family，只放 skill 本体。 +- `skill-workbench/docs/sm-flow/workflow.md`：`sm-flow` 的设计演进文档。 +- `skill-workbench/docs/explore-essence-follow/latest-design.md`：`explore`、`essence`、`follow` 三个学习型 skill 的最新设计总结。 +- `.agents/skills/sm-flow/`：`sm-flow` 的运行时安装副本，用于当前 Codex 会话加载。 +- `skill-workbench/history/changelog/`：早期 skill family 变更记录。 +- `skill-workbench/history/docs/`：早期设计、OpenSpec 与 agent 文档。 +- `skill-workbench/validation/project/`、`skill-workbench/validation/tmp2/`：验证 skill 时使用的第三方源码和临时报告。 +- `skill-workbench/validation/skills-lock.json`：验证安装 mattpocock skills 时生成的锁文件。 diff --git a/devflow/glossary/CONTEXT.md b/devflow/glossary/CONTEXT.md new file mode 100644 index 0000000..ff8c738 --- /dev/null +++ b/devflow/glossary/CONTEXT.md @@ -0,0 +1,41 @@ +# CONTEXT.md — github-learn + +本文件是 github-learn 项目的领域词汇表（glossary only）。不含实现细节、不含规格说明。 + +## 核心术语 + +### 知识条目 (Knowledge Entry) +一个知识条目是 `/knowledge-absorber` 技能的单次输出结果，以 `knowledge_YYYYMMDD_Title/` 命名目录，放置于 `knowledge/entries/`。每个条目内含一对同名的 `.md`（Markdown 源码）和 `.html`（渲染后页面）文件。 + +### 索引面板 (Index Panel) +`knowledge-index.html`——项目根目录下的纯静态 HTML 文件。由 `scripts/update-knowledge-index.sh` 生成。负责汇总所有知识条目并提供搜索和标签导航。 + +### 知识吸收器 (Knowledge Absorber) +全局 skill，位于 `~/.claude/skills/knowledge-absorber/`。接收 URL 或文档，输出知识条目。 + +### 真理源 (Source of Truth) +- **日期**和**短标识符 (slug)**：由目录名 `knowledge_YYYYMMDD_Slug/` 提取。 +- **显示标题**、**tags**、**author**：由 YAML frontmatter 提取。 +详见 [ADR-001](./adr/0001-directory-name-as-truth-source.md)。 + +### 短标识符 (Slug) +目录名中 `YYYYMMDD_` 之后的部分。用于脚本定位目录和构建文件路径。不用于显示（显示标题来自 YAML frontmatter 的 `title` 字段）。 +### 年份筛选 (Year Filter) +索引面板中的全局过滤器。年份来自知识条目的 `date` 字段前四位，即目录名 `knowledge/entries/knowledge_YYYYMMDD_Slug/` 中的 `YYYY`。年份筛选与搜索、标签筛选取交集；选择“全部年份”表示不启用年份过滤。 + +## 目录约定 + +``` +github-learn/ +├── knowledge/ +│ └── entries/ +│ └── knowledge_YYYYMMDD_Title/ # 知识条目（0-N 个） +│ ├── knowledge_YYYYMMDD_Title.md +│ └── knowledge_YYYYMMDD_Title.html +├── knowledge-index.html # 索引面板（由脚本生成） +├── scripts/ +│ └── update-knowledge-index.sh # 索引重建脚本 +├── openspec/ # OpenSpec 当前变更和归档 +├── devflow/ # 人类可读工作流档案 +└── skill-workbench/ # skill 生成、历史文档和验证沙箱 + diff --git a/devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md b/devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md new file mode 100644 index 0000000..b502ad7 --- /dev/null +++ b/devflow/projects/2026-05-18-knowledge-index-panel/adr/0001-directory-name-as-truth-source.md @@ -0,0 +1,39 @@ +# ADR-001: 目录名作为日期和标题的真理源 + +**状态**：已接受 +**日期**：2026-05-18 + +## 背景 + +知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter，其中也有 `date`/`created` 和 `title` 字段，但实际使用中发现字段名不一致（`date` vs `created`）和格式差异。 + +索引重建脚本需要确定日期和标题的权威来源。 + +## 决策 + +**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。** + +- 日期从目录名的 `YYYYMMDD` 部分提取 +- 短标识符从目录名的 `Slug` 部分提取（用于文件路径构建，不用于显示） +- 显示标题从 YAML frontmatter 的 `title` 字段提取 +- `tags` 和 `author` 从 YAML frontmatter 提取 + +## 替代方案 + +| 方案 | 被拒原因 | +|------|---------| +| YAML 全优先 | 字段名不一致（date vs created） | +| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失（如 `mattpocock_skills` → `mattpocock skills`，实际标题更长更精确） + +## 后果 + +### 正面 +- 索引脚本不需要处理日期字段名变体（date vs created） +- 目录名是可见的、可审计的——与 `ls` 输出完全一致 +- bash 用 glob 匹配 `knowledge_*` 目录，天然获取了日期和 slug +- 显示标题从 YAML 取，支持完整的、精确的标题文本（含标点、中文） + +### 负面 +- 索引脚本需要解析 YAML frontmatter（复杂度比仅取目录名高） +- 如果目录被重命名，slug 会变化但显示标题不受影响（可接受的行为） +- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定 diff --git a/devflow/projects/2026-05-18-knowledge-index-panel/knowledge-index-panel-prd.md b/devflow/projects/2026-05-18-knowledge-index-panel/knowledge-index-panel-prd.md new file mode 100644 index 0000000..5d05d46 --- /dev/null +++ b/devflow/projects/2026-05-18-knowledge-index-panel/knowledge-index-panel-prd.md @@ -0,0 +1,57 @@ +# PRD: 知识库索引面板 (Knowledge Index Panel) + +## Problem Statement + +用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。 + +## Solution + +在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。 + +## User Stories + +1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when +2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders +3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics +4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber` +5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup +6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied +7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query +8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most + +## Implementation Decisions + +- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies +- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()` +- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support +- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `` tags for highlighting +- **Tag system**: In-memory `Map` built at load time. Click to filter, click again to deselect +- **Related Content**: Computed from shared tags, displayed per-entry +- **No pagination**: Designed for < 50 entries. Full list rendered at once +- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection + +## Testing Decisions + +- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state +- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures +- **Edge cases to verify**: + - Missing directory (manifest lists a name that doesn't exist) → skip gracefully + - Malformed YAML → display directory name as fallback + - Empty tags array → no tag badges rendered + - No search results → show "没有找到相关条目" message + - Browser CORS when opened via `file://` protocol → document the workaround + +## Out of Scope + +- Google Drive / cloud sync +- Editing knowledge entries +- Full YAML 1.2 spec compliance +- Pagination or virtual scrolling +- Fuse.js or other fuzzy search libraries (keep it zero-dependency) +- Dark mode toggle (can add later, not in v1) + +## Further Notes + +- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array +- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality +- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-acceptance.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-acceptance.md new file mode 100644 index 0000000..2e91a42 --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-acceptance.md @@ -0,0 +1,70 @@ +# 清空所有筛选验收 + +## 结果 + +部分接受：实现和自动化/静态验证已完成，浏览器人工点击验证未运行。 + +## 验证 + +### 静态验证 + +- 命令/检查：`rg -n -F "function clearFilters" knowledge-index.html scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：生成脚本和生成后的 HTML 均包含 `clearFilters()`。 + +- 命令/检查：`rg -n -F "bindClearFilters" knowledge-index.html scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：初始化流程绑定清空按钮点击事件。 + +- 命令/检查：`rg -n -F "tag-badge.active" knowledge-index.html scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：`clearFilters()` 移除所有 active 标签。 + +### 脚本验证 + +- 命令：`C:\Program Files\Git\bin\bash.exe -n scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：脚本语法检查成功。 + +- 命令：`C:\Program Files\Git\bin\bash.exe scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：成功扫描 3 个 `knowledge_*/` 目录并重新生成 `knowledge-index.html`。 + +### 浏览器/人工验证 + +- 步骤：输入搜索词，选择年份，点击一个标签，再点击“清空筛选”。 +- 结果：未运行 +- 备注：当前未打开浏览器做人工点击验证；建议用户本地打开 `knowledge-index.html` 补验。 + +## 已完成范围 + +- 新增“清空筛选”按钮。 +- 新增 `clearFilters()` 统一清空入口。 +- 清空当前支持的搜索、年份、标签筛选。 +- 清空后调用 `applyFilters()` 恢复完整列表。 +- 已在 OpenSpec 中记录未来新增筛选器必须接入统一清空行为。 + +## 已知限制 + +- 未做浏览器人工点击验证。 +- 没有新增 URL query、保存筛选状态或撤销清空功能。 + +## Bug 修复和诊断 + +- 问题：PowerShell `Set-Content -Encoding UTF8` 会把脚本写成带 BOM，Git Bash 执行 shebang 时可能报 `#!/usr/bin/env` 路径异常。 +- 诊断：检查首字节发现 BOM 后，用无 BOM UTF-8 重写脚本。 +- 回归验证：去 BOM 后 `bash -n` 和完整生成脚本均通过。 + +## 交接 + +- 下一步：浏览器人工验证后，可确认是否 archive `add-clear-filters` OpenSpec change。 +- OpenSpec 归档确认：用户已确认归档，已移动到 `openspec/changes/archive/2026-05-19-add-clear-filters/`。 + +## OpenSpec Archive + +- Change：`add-clear-filters` +- Schema：`spec-driven` +- Archived to：`openspec/changes/archive/2026-05-19-add-clear-filters/` +- Specs：未同步；当前仓库没有 `openspec/specs/` 主规格目录可同步。 +- Artifacts：`proposal`、`design`、`specs`、`tasks` 均为 done。 +- Tasks：无未完成 checkbox。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-alignment.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-alignment.md new file mode 100644 index 0000000..ea45f8c --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-alignment.md @@ -0,0 +1,24 @@ +# 清空所有筛选：PRD / Devflow / OpenSpec 对齐记录 + +## 对齐结论 + +当前 PRD、devflow 上下文和 OpenSpec 产物基本一致，可以进入 Phase 2 澄清。 + +## 已对齐项 + +| 项目 | 结论 | 依据 | +| --- | --- | --- | +| 页面真理源 | 必须修改 `scripts/update-knowledge-index.sh` 并重建 HTML | `add-year-filter-acceptance.md` 记录生成脚本是页面真理源 | +| 过滤入口 | `applyFilters()` 是搜索、标签、年份的统一过滤入口 | `add-year-filter-design.md` 模块地图 | +| 清空范围 | 当前 OpenSpec 覆盖搜索、年份、标签三类过滤 | `add-clear-filters/spec.md` | +| 验收方式 | 静态验证 + 脚本验证 + 浏览器/人工验证 | `add-clear-filters/design.md` | + +## 待确认项 + +| 问题 | 类型 | 是否阻塞实现 | +| --- | --- | --- | +| “清空所有筛选”是否应定义为未来新增筛选器也必须接入统一清空入口？ | user-interview | 不阻塞当前实现，但影响 spec 表述和设计约束 | + +## OpenSpec 修正建议 + +如果用户确认要面向未来筛选器，建议把 spec 文案从“search, year, tag filters”扩展为“all currently supported filters”，并在 design 中明确未来新增过滤器必须接入 `clearFilters()`。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-clarifications.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-clarifications.md new file mode 100644 index 0000000..72617da --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-clarifications.md @@ -0,0 +1,18 @@ +# 清空所有筛选：Phase 2 澄清记录 + +## 决策摘要 + +用户选择“未来扩展”语义：清空所有筛选不仅清空当前搜索、年份、标签三类筛选，也定义为未来新增筛选器必须接入统一 `clearFilters()`。 + +## 澄清记录 + +| 维度 | 模式 | 问题 | 证据 / 用户反馈 | 结论 | 是否回写 OpenSpec | +| --- | --- | --- | --- | --- | --- | +| 术语 | evidence-driven | 应使用“筛选 / filter”还是其它术语？ | 页面已有 `applyFilters()`，年份筛选术语已在 glossary 中存在 | 使用“筛选 / filter” | 是 | +| 边界 | user-interview | 清空范围只包括当前筛选器，还是未来筛选器也必须接入？ | 用户确认选择“未来扩展” | 未来新增筛选器必须接入 `clearFilters()` | 是 | +| 验收 | evidence-driven | 如何证明清空完成？ | OpenSpec spec 已覆盖搜索词、年份、标签和高亮清除 | 清空后无搜索词、全部年份、无 active 标签、列表恢复 | 是 | + +## OpenSpec 回写 + +- `openspec/changes/add-clear-filters/specs/knowledge-filtering/spec.md` 已改为 “all currently supported filtering state”，并要求未来筛选器接入同一清空行为。 +- `openspec/changes/add-clear-filters/design.md` 已补充 `clearFilters()` 是统一清空入口。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-design.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-design.md new file mode 100644 index 0000000..42da0cb --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-design.md @@ -0,0 +1,24 @@ +# 清空所有筛选设计 + +## 架构摘要 + +输入是搜索框、年份下拉框和标签 badge 的 UI 状态；处理入口是 `clearFilters()` 清空所有当前支持的筛选器后调用 `applyFilters()`；输出是重新渲染后的完整知识条目列表。 + +## 关键决策 + +- `clearFilters()` 是统一清空入口。 +- 未来新增筛选器时，必须同时接入 `applyFilters()` 和 `clearFilters()`。 +- 实现必须修改 `scripts/update-knowledge-index.sh`，再重建 `knowledge-index.html`。 + +## 模块地图 + +| 模块 | 职责 | 备注 | +| --- | --- | --- | +| `scripts/update-knowledge-index.sh` | 生成 HTML、CSS、JS 模板 | 本次实现真理源 | +| `knowledge-index.html` | 生成后的静态索引页面 | 由脚本重建 | +| `clearFilters()` | 清空所有当前支持的筛选状态 | 新增统一清空入口 | +| `applyFilters()` | 根据当前筛选状态重新过滤并渲染 | 现有统一过滤入口 | + +## 架构审计 + +该功能是纯前端状态重置，不改变 `ENTRIES` 数据源、不影响 `knowledge_*/` 目录、不引入外部依赖。主要风险是未来新增筛选器时忘记接入 `clearFilters()`，因此 OpenSpec design/spec 已回写“未来筛选器必须接入统一清空行为”。另一个风险是只修改生成后的 HTML，因此 Phase 3 必须以 `scripts/update-knowledge-index.sh` 为修改入口。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-prd.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-prd.md new file mode 100644 index 0000000..5e2f1b9 --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-prd.md @@ -0,0 +1,50 @@ +# 清空所有筛选 PRD + +## 问题陈述 + +知识库索引已经支持搜索、标签筛选和年份筛选。用户组合多个筛选条件后，想回到完整列表时需要逐个清空搜索、取消标签、重置年份，操作成本随筛选维度增加而上升。 + +## 解决方案 + +在索引面板的筛选区域增加“清空筛选”按钮。点击后一次性清空当前所有筛选状态，并重新显示完整知识条目列表。 + +## 用户故事 + +1. 作为学习者，我希望一键清空搜索词，以便快速回到完整列表。 +2. 作为学习者，我希望一键取消所有激活标签，以便不用逐个点击标签。 +3. 作为学习者，我希望一键重置年份筛选，以便不用手动切回“全部年份”。 +4. 作为学习者，我希望清空后所有条目重新显示，以便重新开始浏览。 +5. 作为学习者，我希望没有筛选条件时点击按钮也不会报错，以便操作行为稳定。 +6. 作为学习者，我希望搜索高亮在清空后消失，以便页面状态与搜索框一致。 +7. 作为维护者，我希望功能写入生成脚本模板，以便重建 `knowledge-index.html` 后不会丢失。 +8. 作为维护者，我希望清空逻辑集中在一个函数中，以便未来新增筛选器时容易接入。 + +## 实现决策 + +- 决策：清空按钮放在搜索框下方的筛选行，与年份筛选同级。 + - 原因：搜索、年份、标签都属于过滤器，按钮应靠近过滤控件。 + - 影响：需要修改 HTML 模板和 CSS。 +- 决策：新增 `clearFilters()` 统一清空过滤状态。 + - 原因：避免把清空逻辑散落在多个事件处理器中。 + - 影响：未来新增筛选器时应接入该函数。 +- 决策：实现必须修改 `scripts/update-knowledge-index.sh`，再重建 `knowledge-index.html`。 + - 原因：生成脚本是索引页面模板真理源。 + - 影响：只改生成后的 HTML 不算完成。 + +## 测试决策 + +- 静态验证：检查生成后的 HTML 中存在按钮、`clearFilters()` 和事件绑定。 +- 脚本验证：运行生成脚本，确认能成功重建页面。 +- 浏览器/人工验证：组合搜索、年份、标签后点击“清空筛选”，确认所有条目恢复显示。 + +## 非目标 + +- 不新增保存筛选状态。 +- 不新增 URL query 参数同步。 +- 不新增“撤销清空”。 +- 不改变现有搜索、标签、年份筛选语义。 + +## 补充说明 + +- OpenSpec change：`openspec/changes/add-clear-filters/` +- 本 PRD 是用户价值和验收口径说明；执行仍以 OpenSpec specs/tasks 为准。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-research.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-research.md new file mode 100644 index 0000000..7ed047c --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-research.md @@ -0,0 +1,23 @@ +# 清空所有筛选技术调研 + +## 摘要 + +- 变更原因：搜索、标签、年份筛选可以组合生效，但缺少一键恢复完整列表的入口。 +- 变更范围：新增清空筛选按钮、`clearFilters()`、按钮绑定，并更新生成脚本模板。 +- 主要技术方案：以 `clearFilters()` 作为统一清空入口，清空搜索、年份、标签状态后调用 `applyFilters()`。 + +## 源产物 + +- OpenSpec change: `openspec/changes/add-clear-filters/` +- 关联 PRD: `add-clear-filters-prd.md` + +## 关键发现 + +- `scripts/update-knowledge-index.sh` 是页面生成真理源，必须先改脚本再重建 `knowledge-index.html`。 +- 当前过滤状态来自 `#search-input`、`#year-filter`、`.tag-badge.active`。 +- `applyFilters()` 是现有统一过滤入口，`clearFilters()` 应清空状态后复用它。 + +## 假设 + +- “清空所有筛选”采用未来扩展语义：未来新增筛选器必须接入 `clearFilters()`。 +- 当前实现不需要新增状态管理或外部依赖。 diff --git a/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-tasks.md b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-tasks.md new file mode 100644 index 0000000..5255ab7 --- /dev/null +++ b/devflow/projects/2026-05-19-add-clear-filters/add-clear-filters-tasks.md @@ -0,0 +1,20 @@ +# 清空所有筛选任务 + +## 需求追踪 + +| 需求 | 状态 | 备注 | +| --- | --- | --- | +| 清空搜索、年份、标签 | 已完成 | `clearFilters()` 清空三个当前支持的筛选状态 | +| 清空后显示全部条目 | 已完成 | 清空后调用 `applyFilters()` | +| 无筛选时点击不报错 | 已完成 | 函数使用元素存在性检查，重复点击保持全量状态 | +| 清除搜索高亮 | 已完成 | 搜索词清空后重新渲染条目，不再调用高亮 | +| 未来筛选器接入统一清空入口 | 已记录 | OpenSpec spec/design 已写入约束 | + +## 实现任务 + +- [x] 在筛选区域增加“清空筛选”按钮。 +- [x] 实现 `clearFilters()`，清空搜索、年份和标签激活状态。 +- [x] 实现 `bindClearFilters()` 并绑定按钮点击。 +- [x] 清空后调用 `applyFilters()` 恢复列表。 +- [x] 修改 `scripts/update-knowledge-index.sh`。 +- [x] 重新生成 `knowledge-index.html`。 diff --git a/devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md new file mode 100644 index 0000000..b0f30b3 --- /dev/null +++ b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-acceptance.md @@ -0,0 +1,44 @@ +# 按年份筛选知识条目验收 + +## 结果 + +已接受。 + +## 验证 + +- 命令：`C:\Program Files\Git\bin\bash.exe -n scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：需要提升权限运行；普通沙箱中 Git Bash 因 `Win32 error 5` 无法创建 signal pipe。 + +- 命令：`C:\Program Files\Git\bin\bash.exe scripts/update-knowledge-index.sh` +- 结果：通过 +- 备注：成功扫描 3 个 `knowledge_*/` 目录并重新生成 `knowledge-index.html`。 + +- 命令：`rg -n "filter-row|year-filter|buildYearFilter|selectedYear|Year filter" knowledge-index.html` +- 结果：通过 +- 备注：确认生成后的 HTML 包含年份控件、年份选项构建函数和过滤逻辑。 + +## 已完成范围 + +- 页面新增“年份”下拉筛选控件。 +- 年份选项从 `ENTRIES[].date` 自动提取并倒序排列。 +- 年份筛选与标签筛选、全文搜索组合生效。 +- 生成脚本已更新，重建页面后功能不会丢失。 +- `devflow/glossary/CONTEXT.md` 已新增“年份筛选 (Year Filter)”术语。 + +## 已知限制 + +- 当前只支持年份，不支持月份、日期范围或时间线视图。 +- 本次未做浏览器内手动点击验证；已做静态生成和代码路径验证。 +- 当前三个真实条目都在 2026 年，因此实际跨年份过滤需要未来新增其他年份条目后进一步人工验证。 + +## Bug 修复和诊断 + +- 问题：普通沙箱中运行 `bash` 或 Git Bash 失败，报 `Win32 error 5` / signal pipe 创建失败。 +- 诊断：这不是脚本语法错误，而是当前 Windows 沙箱对 MSYS/Git Bash 进程能力的限制；提升权限后 `bash -n` 和生成脚本均成功。 +- 回归验证：已用提升权限运行语法检查和完整生成流程。 + +## 交接 + +- 下一步：如需完成 OpenSpec 生命周期，可归档 `add-year-filter` change。 +- 建议：未来增加 2027 或其他年份条目后，在浏览器中手动确认下拉年份过滤的视觉行为。 diff --git a/devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md new file mode 100644 index 0000000..4372e26 --- /dev/null +++ b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-design.md @@ -0,0 +1,29 @@ +# 按年份筛选知识条目设计 + +## 架构摘要 + +输入是 `ENTRIES` 数组中的知识条目，处理过程是从 `date` 字段提取年份并维护一个全局年份筛选控件，输出是被年份、标签和搜索共同过滤后的条目列表。 + +## Phase 2 澄清结论 + +- 术语问题：使用“年份筛选 (Year Filter)”表示按 `YYYY` 过滤知识条目的全局过滤器；该术语已写入 `devflow/glossary/CONTEXT.md`。 +- 边界问题：本次只支持年份，不支持月份、时间线、日期范围或自定义排序。 +- 验收问题：选择某一年后，只有 `date` 以该年份开头的条目显示；选择“全部年份”后取消年份过滤；年份与搜索、标签取交集。 + +## 关键决策 + +- 年份从 `ENTRIES[].date.slice(0,4)` 派生，不新增数据字段。 +- 控件使用原生 ``。 + - 原因：实现简单、可访问性较好、无外部依赖。 + - 影响：不引入新的 UI 库或复杂状态管理。 +- 决策：年份筛选与标签、搜索取交集。 + - 原因：符合用户对多个过滤条件同时生效的直觉。 + - 影响：`applyFilters()` 需要统一读取三类过滤状态。 + +## 测试决策 + +- 好测试应验证外部行为：选择年份后列表变化，而不是测试内部函数实现。 +- 必须覆盖：默认全部年份、选择具体年份、年份 + 标签 + 搜索组合过滤、重建页面后功能保留。 +- 不测试：复杂日期解析、时区、非 `YYYYMMDD` 的完整兼容性；异常日期只需要不破坏页面。 + +## 非目标 + +- 不增加月份筛选。 +- 不增加时间线视图。 +- 不改变 `knowledge_YYYYMMDD_Slug` 命名约定。 +- 不引入外部依赖或构建工具。 + +## 补充说明 + +- 本功能是 `knowledge-index-panel` 的增量增强。 +- slug 使用 `add-year-filter`。 diff --git a/devflow/projects/2026-05-19-add-year-filter/add-year-filter-research.md b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-research.md new file mode 100644 index 0000000..79c4903 --- /dev/null +++ b/devflow/projects/2026-05-19-add-year-filter/add-year-filter-research.md @@ -0,0 +1,24 @@ +# 按年份筛选知识条目技术调研 + +## 摘要 + +- 变更原因：知识库索引已有搜索和标签过滤，但缺少按年份回顾知识条目的入口。 +- 变更范围：新增年份筛选 UI、年份选项生成逻辑、过滤组合逻辑，并更新生成脚本模板。 +- 主要技术方案：从 `ENTRIES[].date` 的前四位派生年份，使用原生 `` 默认为“全部年份” | +| 选择年份后过滤条目 | 已完成 | `applyFilters()` 按 `date.slice(0,4)` 过滤 | +| 年份与标签、搜索组合生效 | 已完成 | 年份、标签、搜索在同一过滤函数中取交集 | +| 清除年份筛选 | 已完成 | 空 value 表示全部年份 | +| 异常日期处理 | 已完成 | 异常日期不生成选项，指定年份时不匹配 | + +## 实现任务 + +- [x] 创建 `openspec/changes/add-year-filter/` 变更产物。 +- [x] 在 `scripts/update-knowledge-index.sh` 中增加年份筛选样式和 HTML。 +- [x] 增加 `buildYearFilter()` 和 `bindYearFilter()`。 +- [x] 在 `applyFilters()` 中加入年份过滤。 +- [x] 重新生成 `knowledge-index.html`。 +- [x] 验证生成脚本和生成结果。 diff --git a/devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md b/devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md new file mode 100644 index 0000000..a7bcb19 --- /dev/null +++ b/devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md @@ -0,0 +1,116 @@ +# Dev Flow Skill 评估报告 + +**日期**：2026-05-19 +**对象**：`.claude/skills/dev-flow/SKILL.md` +**背景**：该 skill 基于 openspec 工作流，并融合 `to-prd`、`grill-with-docs`、`zoom-out`、`diagnose`、`tdd` 等开源 skill 思路，目标是形成一套从需求到实现再到知识沉淀的工程开发闭环。 + +## 总体评价 + +这套 `dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。 + +最有价值的设计是 `devflow/` 产物聚合层： + +- `openspec/changes/` 负责机器可执行的变更工作区。 +- `devflow/projects/` 负责人类可回溯的项目档案。 +- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。 +- `devflow/compound/` 负责沉淀可复用工程知识。 + +目前最大的问题是：`SKILL.md` 更像一份设计说明书，而不是一份代理可以稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。 + +## 亮点 + +1. **产物聚合层设计清晰** + - `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。 + - 工具工作区和人类档案层分离，职责边界明确。 + +2. **阶段顺序合理** + - Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。 + +3. **Phase 4 很有价值** + - 明确要求从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。 + - 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。 + +4. **grill-with-docs 融合方式正确** + - Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。 + - 这符合“边澄清边沉淀”的工作方式。 + +5. **质量闭环意识强** + - Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。 + - TDD 被设计为可选增强，避免对所有任务强制套用重流程。 + +## 主要问题 + +1. **触发描述不够完整** + - 当前 `description` 说明了流程构成，但没有覆盖足够多的用户触发场景。 + - 建议明确写入：当用户要从需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程时使用。 + +2. **Claude 工具耦合较强** + - `allowed-tools` 使用 Claude Code 风格工具名。 + - 如果未来迁移到 Codex skill，这些工具名可能不适用。 + - 建议把工具白名单保留给 Claude 版本，同时在正文中描述环境无关的 fallback 行为。 + +3. **依赖安装状态不应写死** + - 依赖表中写了“✅ 已安装”，这对当前仓库成立，但复制到其他项目会误导。 + - 应改成“启动时检查是否存在”，并区分 required、optional、fallback。 + +4. **子 skill 调用方式不稳** + - 文档写“调用 Skill 工具启动 openspec-propose / openspec-apply-change”。 + - 但不同代理环境未必支持直接调用 Skill 工具。 + - 建议增加 fallback：如果不能直接调用，就读取对应 `SKILL.md` 并按其协议执行。 + +5. **缺少初始化算法** + - 文档要求写入 `devflow/projects/YYYY-MM-DD-{slug}/`，但没有说明如何生成 slug、如何处理重名、如何创建目录骨架。 + +6. **缺少模板** + - PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 都有路径要求，但没有最小模板。 + - 这会导致代理每次输出格式不稳定。 + +7. **quick 模式与约束存在冲突** + - `--quick` 说可以跳 Phase 1.5 和 2.5，仅 grill + apply。 + - 约束又说严禁跳过 Phase 2。 + - 需要明确 quick 模式只能跳哪些阶段，不能跳哪些阶段。 + +8. **Phase 退出条件不足** + - 每个 Phase 有目标，但没有明确“什么时候可以进入下一阶段”。 + - 建议增加进入条件、退出条件和必需产物。 + +## 改进建议 + +1. **将 `SKILL.md` 改成执行协议** + - 保留角色、触发场景、阶段总览、硬性约束和关键分支规则。 + - 把长解释、模板、示例迁移到 `references/`。 + +2. **增加启动前检查清单** + - 检查 `openspec/` 是否存在。 + - 检查 `.claude/skills/openspec-*` 是否存在。 + - 检查 `devflow/` 是否已初始化。 + - 检查是否存在旧的根目录 `CONTEXT.md`，必要时迁移或合并到 `devflow/glossary/CONTEXT.md`。 + +3. **增加 Phase 契约** + - 每个 Phase 明确：输入、动作、输出、退出条件、失败时回退路径。 + +4. **补齐模板** + - 新增 `references/templates.md`，收纳 PRD、research、design、tasks、acceptance、ADR、compound knowledge 的最小模板。 + +5. **补齐归档规则** + - 新增 `references/archive-rules.md`，明确如何从 openspec 文件提取信息到 `devflow/projects/`。 + +6. **统一 quick 模式语义** + - quick 模式可以跳过 Phase 1.5 和 Phase 2.5。 + - quick 模式不能跳过 Phase 2 的最小澄清，也不能跳过 Phase 4 的轻量归档。 + +7. **增加 fallback 策略** + - 优先调用子 skill。 + - 如果不可调用，则读取该 skill 的 `SKILL.md`。 + - 如果 skill 文件不存在，则执行 dev-flow 内置的最小协议。 + +## 优先级 + +- **P0**：修正工具/环境耦合、依赖检查、quick 模式冲突。 +- **P1**：补模板和 Phase 退出条件。 +- **P2**：把长理念迁移到 `references/`，保持 `SKILL.md` 更短更可执行。 +- **P3**：增加 `agents/openai.yaml` 或等价元数据，方便技能列表展示。 + +## 结论 + +`dev-flow` 已经具备成为高价值工程元技能的基础：流程完整、沉淀意识强、质量闭环明确。下一步不应继续增加理念，而应把它产品化为“代理稳定执行协议”：更短的 `SKILL.md`、更明确的 Phase 契约、更标准的模板、更稳的 fallback 机制。 diff --git a/devflow/projects/2026-05-19-dev-flow-skill-evaluation/todo.md b/devflow/projects/2026-05-19-dev-flow-skill-evaluation/todo.md new file mode 100644 index 0000000..b5f869e --- /dev/null +++ b/devflow/projects/2026-05-19-dev-flow-skill-evaluation/todo.md @@ -0,0 +1,44 @@ +# Dev Flow Skill 改进 TODO + +## P0：先修正执行稳定性 + +- [x] 重写 `description`，覆盖需求规划、feature 开发、openspec change、工程文档沉淀等触发场景。 +- [x] 将依赖表中的“✅ 已安装”改为“启动时检查”，区分 required、optional、fallback。 +- [x] 为子 skill 调用增加 fallback：优先调用 skill，不可调用时读取对应 `SKILL.md`，不存在时执行内置最小协议。 +- [x] 明确 `--quick` 模式：允许跳 Phase 1.5 和 Phase 2.5；禁止跳 Phase 2 最小澄清和 Phase 4 轻量归档。 +- [x] 增加 `devflow/` 初始化规则：创建 `projects/`、`glossary/`、`compound/`、`reference/`，并处理旧 `CONTEXT.md`。 +- [x] 增加 v3 OpenSpec-first 规则：devflow 辅助 OpenSpec，OpenSpec 指挥执行。 +- [x] 增加显式子 skill 调用规则：不能调用时必须标记 fallback 降级。 +- [x] 增加 devflow 产物分档：micro / standard / complex，避免默认产物过多。 + +## P1：补齐 Phase 契约和模板 + +- [x] 为 Phase 0 增加进入条件、退出条件、最小输入质量标准。 +- [x] 为 Phase 1 增加 openspec 产物检查：`proposal.md`、`design.md`、`specs/`、`tasks.md`。 +- [x] 为 Phase 1.5 增加 PRD/brief 最小模板和完成标准。 +- [x] 为 Phase 2 增加 `CONTEXT.md` 更新模板和 ADR 创建判断模板。 +- [x] 为 Phase 2.5 增加架构审计输出模板。 +- [x] 为 Phase 3 增加 diagnose 触发条件和 TDD 触发条件。 +- [x] 为 Phase 4 增加 acceptance report 模板和 openspec 提取规则。 + +## P2：重构 skill 文件结构 + +- [x] 将新版本迁移为 `.agents/skills/sm-flow/SKILL.md` 短执行协议。 +- [x] 新建 `.agents/skills/sm-flow/references/templates.md`，存放所有文档模板。 +- [x] 新建 `.agents/skills/sm-flow/references/phase-contracts.md`，存放 Phase 输入/动作/输出/退出条件。 +- [x] 新建 `.agents/skills/sm-flow/references/archive-rules.md`，存放 Phase 4 提取和归档规则。 +- [x] 新建 `.agents/skills/sm-flow/references/fallbacks.md`，存放子 skill 不可用时的最小协议。 +- [x] 删除或迁移 `SKILL.md` 中过长的理念说明，避免上下文膨胀。 + +## P3：完善展示和可移植性 + +- [ ] 评估是否需要 `agents/openai.yaml` 或其他技能展示元数据。 +- [ ] 增加一个最小示例项目，验证从 Phase 0 到 Phase 4 的完整流转。 +- [ ] 增加“复制到新项目后首次运行”的检查步骤。 +- [ ] 明确 Claude 版本与 Codex 版本的差异，避免工具名耦合。 + +## 建议执行顺序 + +1. 先改 `SKILL.md` 的触发描述、依赖检查、quick 模式和 fallback 规则。 +2. 再拆出 `references/` 模板与 Phase 契约。 +3. 最后用一个真实小需求跑通 Phase 0 到 Phase 4，回填发现的问题。 diff --git a/knowledge-index.html b/knowledge-index.html new file mode 100644 index 0000000..036def0 --- /dev/null +++ b/knowledge-index.html @@ -0,0 +1,298 @@ + + + + + +知识库索引 — github-learn + + + +
+
+

知识库索引

+
github-learn · 共 0 条知识条目
+
+
+ +
+ +
+ +
+ +
+ + + +
+ +
没有找到匹配的条目
+ +
+ +
+ +
+由 scripts/update-knowledge-index.sh 生成 · +
+ +
+ + + + diff --git a/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.html b/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.html new file mode 100644 index 0000000..75be042 --- /dev/null +++ b/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.html @@ -0,0 +1,498 @@ + + + + + +Waza — 把工程师的习惯变成 Claude 可执行的技能 + + + + +
+ + +
+ +
+ + +
+

Waza：把工程习惯变成 Claude 可执行的技能

+
+ 作者：叫我小杨同学的小码酱 + 日期：2026-04-17 + 标签：Claude Code / Skills / 工程习惯 +
+
+ + +

核心摘要

+
+

一句话核心：Waza（技）把优秀工程师的思维方式打包成 8 个 Claude Code 技能 —— 不是替你写代码更快，而是逼你想清楚再动手。

+
认知挂钩：像道场里的型（Kata）。每个技能是一个固定套路，练到变成肌肉记忆。
+
真理锚点："AI makes you faster. It doesn't make you think more clearly."
+
+ + +

概念破冰

+ +
+ 八字口诀：思设审猎，写学读健 + + + + + + + + + + +
字技能阶段
思/think动手前：挑战问题、压力测试设计
设/design做界面：产出有辨识度的 UI
审/check合并前：自审 diff、标记危险操作
猎/hunt出 bug 时：系统调试、确认根因再修
写/write写文档：中英双语自然表达
学/learn新领域：六阶段研究 → 输出 → 自审 → 发布
读/read读资料：URL/PDF 转干净 Markdown
健/health定期体检：CLAUDE.md、rules、skills、hooks、MCP
+
+ +

架构概览

+
++-----------------------------------------------+ +| Waza 技能矩阵 | ++-----------------------------------------------+ +| | +| /think → /design → /check /hunt | +| 思考 设计 审查 调试 | +| ↑ ↑ | +| └────── /write ────────────┘ | +| 写作 | +| | +| /learn /read /health | +| 学习 阅读 体检 | +| 输入 ──────→ 转化 ──────→ 输出 | ++-----------------------------------------------+
+ + +

深度解析

+ +

哲学：为什么是"习惯"而不是"规则"？

+

Waza 的名字来自日语"技"（わざ），武道中意为"练到成本能的招式"。这与市面上大多数 AI 技能包有根本区别。

+ + + + + + + +
维度规则驱动（Superpowers/gstack）习惯驱动（Waza）
指令风格大量 rules，步步规定设目标 + 约束，然后放手
模型上限指令写多少，模型做多少约束关键边界，其余自由发挥
模型进化模型变强后，旧规则变束缚模型变强，收益复利增长
学习曲线陡峭，配置多扁平，一个技能一个触发场景
+ +

工程生命周期

+ +
+
+flowchart TD + A["开始新任务"] --> B["/read: 读取相关文档"] + B --> C["/think: 挑战问题，验证架构"] + C --> D{"前端界面?"} + D -->|"是"| E["/design: 产出有审美的 UI"] + D -->|"否"| F["编码实现"] + E --> F + F --> G{"遇到 bug?"} + G -->|"是"| H["/hunt: 系统调试"] + G -->|"否"| I["/check: 自审 diff"] + H --> I + I --> J{"写作/文档?"} + J -->|"是"| K["/write: 润色中英双语"] + J -->|"否"| L["完成"] + K --> L + M["定期"] --> N["/health: 体检环境"] + O["新领域"] --> P["/learn: 六阶段研究"] +
+
+ +

逐技能拆解

+ +

/think —— 先想清楚再动手。挑战问题本身。需求是真的吗？有没有更简单的解法？防止"用正确的方式做错误的事"。

+ +

/design —— 界面要有辨识度。产出有明确审美方向的 UI，不是千篇一律的默认样式。

+ +

/check —— 合并前的最后一道关。审查 diff，自动修复安全的问题，标记危险命令，用证据说话。支持并行多专家审查。

+ +

/hunt —— 系统调试，不靠猜。先复现，再定位，确认根因后才修。

+ +

/write —— 像人一样写文章。重写中英双语，去掉生硬公式化表达。

+ +

/learn —— 六阶段研究法。收集 → 消化 → 大纲 → 填充 → 精炼 → 自审 → 发布。学习靠产出驱动。

+ +

/read —— 把一切变成干净 Markdown。特殊处理 GitHub、PDF、微信、飞书。

+ +

/health —— Claude 环境的体检报告。检查 CLAUDE.md、rules、skills、hooks、MCP，按严重程度分级。

+ +

项目起源

+

Waza 来自真实项目的失败积累：找错代码路径来回 4 轮才定位、发布 release 前忘了上传 artifacts、服务器重启 8 次都没看报错信息。30 天、300+ 次会话、7 个项目、500 小时 —— 每个 "gotcha" 对应一次真实失败。

+ + +
+

深度裂变

+ +

矛盾一："不完整是设计出来的"

+
"Waza 只有 8 个技能。不是做不到更多，而是刻意不做完。"
+

市面上的 AI 技能包动辄几十个技能。Waza 反其道：八个习惯，每个做一件事，有明确触发条件，然后让路。对 AI 工具来说，"够用"比"全能"更有价值。

+ +

矛盾二："每条规则都是天花板"

+
"作者写的每一条规则，都成了模型能力的上限。"
+

传统做法是"把所有规则写进 prompt"，隐含假设是作者比模型聪明。Waza 的做法是"设目标 + 约束，然后放手"——等模型变强了，自由度带来的收益呈复利。

+ +

矛盾三："英文推理更强"的隐性红利

+
"大多数 AI 模型的英文训练量远超其他语言。"
+

母语写 prompt → 隐形翻译层 → 推理质量打折。切换英文后，回答更精准，顺便练英语。Waza 提供 english.md 规则让 Claude 在英文交互时即时纠错。

+
+ + +

实战指南

+ +

安装

+ 
# Claude Code
+npx skills add tw93/Waza -a claude-code -g -y
+
+# Codex
+npx skills add tw93/Waza -a codex -g -y
+
+# Statusline
+curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-statusline.sh | bash
+
+# 英文教练
+mkdir -p ~/.claude/rules && curl -fsSL https://raw.githubusercontent.com/tw93/Waza/main/rules/english.md -o ~/.claude/rules/english.md
+ +

避坑指南

+ + + + + + + +
反模式后果正确做法
跳过 /think 直接写做了错误的事，返工成本高再急也先想 5 分钟
/hunt 时直接猜修复埋新雷先复现，确认根因
不看 /check 结果就合并危险命令进主干审查完再合
装了技能从不调用形同虚设养成肌肉记忆
忽略 /health配置逐渐腐烂每周跑一次
+ +

ROI 分析

+ + + + + + +
投入回报
安装 5 分钟每个任务避免至少 1 次返工
/think 多花 5 分钟可能省下 2 小时重写
/check 多花 2 分钟避免线上事故
/learn 多花 30 分钟产出 > 消费 10 倍效率
+ + +

温故知新

+ +

FAQ

+ +
+ Q1: Waza 和其他技能包有什么区别？ +

Superpowers 和 gstack 功能更全但更重。Waza 只做 8 个最核心的习惯。哲学不同：规则驱动 vs 习惯驱动。

+
+ +
+ Q2: 只能在 Claude Code 里用吗？ +

不。/health 是 Claude Code 独有的。其余 7 个技能也支持 Codex。

+
+ +
+ Q3: 可以自己改技能吗？ +

可以。每个技能是一个文件夹，MIT 协议。包含参考文档、辅助脚本、gotchas。

+
+ +
+ Q4: 适合什么水平的开发者？ +

有工程经验但想更系统化的开发者。已有习惯 → 帮你自动化；还没养成 → 逼你养成。

+
+ +
+ Q5: "Waza" 怎么念？ +

日语「技」（わざ / waza），发音类似 "哇扎"。

+
+ +
+ Q6: 作者 tw93 是谁？ +

活跃在 GitHub 和 Twitter 的独立开发者，MiaoYan 等项目的作者。养了两只猫：汤圆和可乐。

+
+ +
+ Q7: 最新版本？ +

截至 2026-04-17，最新版本 V3.10.0，252 commits，3.3k+ stars，202 forks。

+
+ +
+ Q8: 怎么卸载？ + 
npx skills remove tw93/Waza -g
+rm -f ~/.claude/statusline.sh
+rm -f ~/.claude/rules/english.md
+
+ +
+

自测题

+
    +
  1. Waza 的核心哲学是什么？为什么"不完整是设计出来的"？
    2. +
  2. 8 个技能分别是什么？各自在什么场景触发？
    3. +
  3. 跳过 /think 直接编码，最大风险是什么？举例说明。
    4. +
  4. 描述从接到需求到合并代码的完整 Waza 工作流。
    5. +
  5. Waza 只有 8 个技能。你觉得缺了什么？为什么作者可能故意不做？
    6. +
  6. 如何在现有工作流中引入 Waza 技能？哪些最容易养成习惯？
    7. +
  7. 如果你要给 Waza 贡献第 9 个技能，会是什么？写 SKILL.md 大纲。
    8. +
+
+ +

参考资源

+ + +
+

叫我小杨同学的小码酱 | 2026-04-17 | 基于 Waza 项目分析生成

+
+ +
+ + + + + + + + + + \ No newline at end of file diff --git a/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.md b/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.md new file mode 100644 index 0000000..4b012fb --- /dev/null +++ b/knowledge/entries/knowledge_20260417_Waza/knowledge_20260417_Waza.md @@ -0,0 +1,339 @@ +--- +title: "Waza — 把工程师的习惯变成 Claude 可执行的技能" +author: "叫我小杨同学的小码酱" +tags: ["Claude Code", "Skills", "AI 辅助开发", "工程习惯", "tw93"] +date: "2026-04-17" +--- + +# Waza：你知道的工程习惯，变成 Claude 能跑的技能 + +> **一句话核心**：Waza（技）把优秀工程师的思维方式打包成 8 个 Claude Code 技能 —— 不是替你写代码更快，而是逼你想清楚再动手。 +> +> **认知挂钩**：像道场里的型（Kata）。每个技能是一个固定套路，练到变成肌肉记忆。 +> +> **真理锚点**：*"AI makes you faster. It doesn't make you think more clearly."* + +--- + +## 模块 0：核心摘要 (TL;DR) + +Waza 是开发者 **tw93** 开源的 Claude Code 技能集（3.3k+ Stars），将 8 个核心工程习惯封装为 `/` 斜杠命令。它不追求"全能"，而是聚焦**真正重要的习惯**：先思考再动手、写完自己审、bug 系统排查、界面有审美、文章写得顺、新领域靠输出学、文档当一手资料读、开发环境定期体检。 + +**生活类比**：不是给你一把更快的锤子，而是教你先看图纸、再选工具、最后才敲。 + +--- + +## 模块 1：概念破冰 + +### 巧记卡片 + +
+ +**八字口诀**：**思设审猎，写学读健** + +| 字 | 技能 | 阶段 | +|---|---|---| +| **思** | `/think` | 动手前：挑战问题、压力测试设计 | +| **设** | `/design` | 做界面：产出有辨识度的 UI | +| **审** | `/check` | 合并前：自审 diff、标记危险操作 | +| **猎** | `/hunt` | 出 bug 时：系统调试、确认根因再修 | +| **写** | `/write` | 写文档：中英双语自然表达 | +| **学** | `/learn` | 新领域：六阶段研究 → 输出 → 自审 → 发布 | +| **读** | `/read` | 读资料：URL/PDF 转干净 Markdown | +| **健** | `/health` | 定期体检：CLAUDE.md、rules、skills、hooks、MCP | + +
+ +### 故事引入 + +想象两个工程师。 + +A 接到需求直接写代码，写完直接提交。遇到 bug 就猜，试十个地方碰巧修好。文档写得像机翻。 + +B 接到需求先问：这个问题真的存在吗？有没有更简单的解法？写完代码自己过一遍 diff。遇到 bug 不猜，先复现、定位、确认根因再修。文档写得连外行都能懂。 + +AI 让 A 写得更快了，但还是 A。AI 让 B 变成了超级 B。 + +Waza 就是给 B 准备的那套工具。 + +### 架构概览 + +``` +┌─────────────────────────────────────────────────┐ +│ Waza 技能矩阵 │ +├─────────────────────────────────────────────────┤ +│ │ +│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ +│ │/think │→ │/design│→ │/check │ │/hunt │ │ +│ │ 思考 │ │ 设计 │ │ 审查 │ │ 调试 │ │ +│ └───────┘ └───────┘ └───────┘ └───────┘ │ +│ ↑ ↑ │ +│ │ ┌───────┐ │ │ +│ └────────│/write │───────────┘ │ +│ │ 写作 │ │ +│ └───────┘ │ +│ │ +│ ┌───────┐ ┌───────┐ ┌───────┐ │ +│ │/learn │ │ /read │ │/health│ │ +│ │ 学习 │ │ 阅读 │ │ 体检 │ │ +│ └───────┘ └───────┘ └───────┘ │ +│ 输入 ──────→ 转化 ──────→ 输出 │ +│ │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## 模块 2：深度解析 + +### 哲学：为什么是"习惯"而不是"规则"？ + +Waza 的名字来自日语"技"（わざ），武道中意为"练到成本能的招式"。这与市面上大多数 AI 技能包有根本区别： + +**规则驱动 vs 习惯驱动** + +| 维度 | 规则驱动（Superpowers/gstack 类） | 习惯驱动（Waza） | +|---|---|---| +| 指令风格 | 大量 detailed rules，步步规定 | 设目标 + 约束，然后放手 | +| 模型上限 | 指令写多少，模型做多少——指令成了天花板 | 约束关键边界，其余让模型自由发挥 | +| 模型进化 | 模型变强后，旧规则可能变成束缚 | 模型变强，自由度带来的收益呈复利增长 | +| 学习曲线 | 陡峭，配置多 | 扁平，每个技能一个触发场景 | + +**核心洞察**：作者写下的每一条规则都成了模型能力的天花板。Waza 反其道而行——每个技能设明确目标，退后一步让模型发挥。 + +### 8 个技能的工程生命周期 + +```mermaid +flowchart TD + A["开始新任务"] --> B["/read: 读取相关文档、RFC、PR"] + B --> C["/think: 挑战问题本身，验证架构"] + C --> D{"前端界面?"} + D -->|"是"| E["/design: 产出有审美的 UI"] + D -->|"否"| F["编码实现"] + E --> F + F --> G{"遇到 bug?"} + G -->|"是"| H["/hunt: 系统调试，确认根因"] + G -->|"否"| I["/check: 自审 diff"] + H --> I + I --> J{"写作/文档?"} + J -->|"是"| K["/write: 润色中英双语"] + J -->|"否"| L["完成"] + K --> L + M["定期"] --> N["/health: 体检 Claude 环境"] + O["遇到新领域"] --> P["/learn: 六阶段研究"] +``` + +### 逐技能拆解 + +#### 1. `/think` — 先想清楚，再动手 + +**触发**：开始任何新任务之前。 +**做什么**：挑战问题本身。需求是真的吗？有没有更简单的解法？架构有没有隐患？ +**核心价值**：防止"用正确的方式做错误的事"——这是工程师最常见的浪费。 + +#### 2. `/design` — 界面要有辨识度 + +**触发**：构建前端界面时。 +**做什么**：产出有明确审美方向的 UI，不是千篇一律的默认样式。 +**核心价值**：AI 默认生成"能用但丑"的界面。这个技能逼 Claude 做出有设计感的东西。 + +#### 3. `/check` — 合并前的最后一道关 + +**触发**：完成任务后、合并代码前。 +**做什么**：审查 diff，自动修复安全的问题，标记危险命令，用证据说话。 +**核心价值**：像老工程师坐在你旁边 review——但比你主动。支持并行多专家审查（宿主环境支持时）。 + +#### 4. `/hunt` — 系统调试，不靠猜 + +**触发**：任何 bug 或异常行为。 +**做什么**：先复现，再定位，确认根因后才修。 +**核心价值**：工程师最容易犯的错——看到 bug 就猜。猜 10 次碰巧修了 1 次，剩下 9 次埋了新雷。 + +#### 5. `/write` — 像人一样写文章 + +**触发**：撰写或编辑文档。 +**做什么**：重写中英双语，去掉生硬公式化表达。 +**核心价值**：AI 生成的文档读起来像翻译腔。这个技能让文字有"人味"。 + +#### 6. `/learn` — 六阶段研究法 + +**触发**：深入不熟悉的领域。 +**流程**：收集 → 消化 → 大纲 → 填充 → 精炼 → 自审 → 发布。 +**核心价值**：学习新领域靠产出驱动，而不是消费内容。先写再改再发。 + +#### 7. `/read` — 把一切变成干净 Markdown + +**触发**：任何 URL 或 PDF。 +**做什么**：抓取内容转为干净 Markdown，特殊处理 GitHub、PDF、微信、飞书。 +**核心价值**：省去手动复制粘贴和格式清理的时间。 + +#### 8. `/health` — Claude 环境的体检报告 + +**触发**：审计 Claude Code 设置时。 +**检查项**：CLAUDE.md、rules、skills、hooks、MCP、行为表现。 +**核心价值**：按严重程度分级标记问题，防止配置腐烂。基于作者的[六层框架](https://tw93.fun/en/2026-03-12/claude.html)。 + +### 项目起源与数据 + +Waza 不是凭空设计的。它来自真实项目的失败积累： +- 找错代码路径，来回 4 轮才定位 +- 发布 release 前忘了上传 artifacts +- 服务器重启 8 次都没看报错信息 + +**30 天、300+ 次会话、7 个项目、500 小时** —— 每个 "gotcha" 都对应一次真实失败。 + +--- + +## 模块 3：深度裂变 + +
+ +### 矛盾分析 & 常识颠覆 + +#### 1. "不完整是设计出来的" + +> Waza 只有 8 个技能。不是做不到更多，而是**刻意不做完**。 + +市面上的 AI 技能包动辄几十个技能，每个覆盖一个小场景。Waza 反其道：**八个习惯，每个做一件事，有明确触发条件，然后让路**。 + +**核爆级结论**：对 AI 工具来说，"够用"比"全能"更有价值。因为每个技能都是独立可调用的，组合起来覆盖工作流全链路，但每个单独调用时负担极小。 + +#### 2. "每条规则都是天花板" + +> 作者写的每一条规则，都成了模型能力的上限。 + +这是 Waza 最反直觉的设计哲学。传统做法是"把所有规则写进 prompt"，但这隐含一个假设：作者比模型聪明。Waza 的做法是"设目标 + 约束，然后放手"——等模型变强了，自由度带来的收益会呈复利。 + +**搜索内化**：在 2026 年的 AI 辅助开发社区中，"less prompt engineering, more outcome-driven constraints" 正成为新共识。Waza 是这一理念的极端实践者。 + +#### 3. "英文推理更强"的隐性红利 + +> 项目专门提供了 English Coaching 规则，建议用英文与 AI 交互。 + +理由很朴素：大多数 AI 模型的英文训练量远超其他语言。母语写 prompt → 隐形翻译层 → 推理质量打折。切换英文后，回答更精准，顺便练英语。 + +**争议点**：这对非英语母语用户有门槛。Waza 的做法是**不强求**，但提供工具（`english.md` 规则）让 Claude 在英文交互时即时纠错。 + +
+ +--- + +## 模块 4：实战指南 + +### 如何开始 + +```bash +# 一步安装所有技能（Claude Code） +npx skills add tw93/Waza -a claude-code -g -y + +# 一步安装所有技能（Codex） +npx skills add tw93/Waza -a codex -g -y + +# 可选：安装 statusline 显示上下文用量 +curl -sL https://raw.githubusercontent.com/tw93/Waza/main/scripts/setup-statusline.sh | bash + +# 可选：安装英文教练规则 +mkdir -p ~/.claude/rules && curl -fsSL https://raw.githubusercontent.com/tw93/Waza/main/rules/english.md -o ~/.claude/rules/english.md +``` + +### 推荐工作流 + +``` +需求来了 → /think 先挑战问题 + → /read 读取相关文档 + → 编码（前端先 /design） + → 遇到 bug → /hunt + → 写完 → /check 自审 + → 写文档 → /write 润色 + → 新领域 → /learn 研究 + → 定期 → /health 体检 +``` + +### 避坑指南 + +| 反模式 | 后果 | 正确做法 | +|---|---|---| +| 跳过 `/think` 直接写 | 做了错误的事，返工成本高 | 再急也先想 5 分钟 | +| `/hunt` 时直接猜修复 | 埋新雷 | 先复现，确认根因 | +| 不看 `/check` 结果就合并 | 危险命令进主干 | 审查完再合 | +| 装了技能从不调用 | 形同虚设 | 养成肌肉记忆，每次任务触发对应技能 | +| 忽略 `/health` | 配置逐渐腐烂 | 每周跑一次 | + +### ROI 分析 + +| 投入 | 回报 | +|---|---| +| 安装 5 分钟 | 每个任务避免至少 1 次返工 | +| `/think` 多花 5 分钟 | 可能省下 2 小时重写 | +| `/check` 多花 2 分钟 | 避免线上事故 | +| `/learn` 多花 30 分钟 | 产出 > 消费 10 倍效率 | + +--- + +## 模块 5：温故知新 + +### FAQ + +
+Q1: Waza 和其他 Claude Code 技能包（如 Superpowers、gstack）有什么区别？ +

Superpowers 和 gstack 功能更全但更重——技能多、配置多、学习曲线陡。Waza 只做 8 个最核心的习惯，每个一件事，触发条件清晰。哲学不同：规则驱动 vs 习惯驱动。

+
+ +
+Q2: 只能在 Claude Code 里用吗？ +

不。/health 是 Claude Code 独有的（需要检查环境）。其余 7 个技能使用宿主环境的原生 question/search/fetch/agent 机制，也支持 Codex。

+
+ +
+Q3: 这些技能是固定死的吗？可以自己改吗？ +

每个技能是一个文件夹（不只是 Markdown 文件），包含参考文档、辅助脚本、gotchas。你可以 fork 后按需修改。MIT 协议。

+
+ +
+Q4: Waza 适合什么水平的开发者？ +

有工程经验但想更系统化的开发者。如果你已经有这些习惯，Waza 帮你自动化。如果你还没有，Waza 逼你养成。

+
+ +
+Q5: "Waza" 这个名字怎么念？ +

日语「技」（わざ / waza），发音类似 "哇扎"。在武道中指"练到成本能的招式"。

+
+ +
+Q6: 作者 tw93 是谁？ +

活跃在 GitHub 和 Twitter 的独立开发者，也是 MiaoYan 等项目的作者。养了两只猫：汤圆和可乐。

+
+ +
+Q7: 最新版本是什么？ +

截至 2026-04-17，最新版本为 V3.10.0，包含 252 次 commits，3.3k+ stars，202 forks。

+
+ +
+Q8: 怎么卸载？ +
# 移除所有技能
+npx skills remove tw93/Waza -g
+
+# 移除 statusline
+rm -f ~/.claude/statusline.sh
+# 然后从 ~/.claude/settings.json 中删除 statusLine 键
+
+# 移除英文教练
+rm -f ~/.claude/rules/english.md
+
+ +### 自测题 + +1. **理解层**：Waza 的核心哲学是什么？为什么"不完整是设计出来的"？ +2. **记忆层**：8 个技能分别是什么？各自在什么场景触发？ +3. **分析层**：如果跳过 `/think` 直接编码，最大的风险是什么？请举一个你经历过的例子。 +4. **应用层**：你接手一个全新项目，描述从接到需求到合并代码的完整 Waza 工作流。 +5. **批判层**：Waza 只有 8 个技能。你觉得缺了什么？为什么作者可能故意不做？ +6. **迁移层**：你如何在现有工作流中引入 Waza 技能？哪些最容易养成习惯？哪些最难？ +7. **创造层**：如果你要给 Waza 贡献第 9 个技能，会是什么？写一个简短的 SKILL.md 大纲。 + +### 参考资源 + +- [tw93/Waza GitHub 仓库](https://github.com/tw93/Waza) +- [作者博客：Claude Code 六层框架](https://tw93.fun/en/2026-03-12/claude.html) +- [Waza 演示推文](https://x.com/HiTw93/status/2041312649510822103) diff --git a/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.html b/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.html new file mode 100644 index 0000000..0f0bea4 --- /dev/null +++ b/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.html @@ -0,0 +1,825 @@ + + + + + +mattpocock/skills 深度解析：AI Agent 工作流的工程化革命 + + + + + +
+
+

mattpocock/skills 深度解析：AI Agent 工作流的工程化革命

+
+ 叫我小杨同学的小码酱 + 2026-05-18 +
+
+ Claude Code + Agent Skills + AI Engineering + Workflow + Matt Pocock + SKILL.md +
+
+
+ +
+ + + + +
+

📌 核心摘要

+
+

Matt Pocock 将自己在 Claude Code 中打磨了数月的 AI 协作工作流，打包成可复用、可组合的 SKILL.md 技能包，开启了"AI 技能包管理"的工程化时代。

+
认知挂钩：就像 jQuery 插件让前端开发从"每次都从头写 JS"进化到"装个插件就行"，mattpocock/skills 让 AI 编程从"每次都从头调教 AI"进化到"装个 Skill 就行"——它定义了 AI Agent 指令的封装标准。
+
真理锚点："Skills for Real Engineers. Straight from my .claude directory." —— Matt Pocock
+
+
+ + +
+

🧊 概念破冰

+ +
AI 编程三板斧： +一装技能包，行为有 template（模板化） +二写 SKILL.md，流程有 blueprint（蓝图化） +三用 npx skills，分发有 package（工程化）
+ +
+
📖 故事引入
+

想象一下：你新招了一个能力超强的实习生 Claude。每次让他写代码，你都得花 20 分钟交代一遍："先写测试、再实现、再重构。不要直接改代码，先问我。Git push 之前必须确认。"

+

一个月后你崩溃了——每次对话都要重新教一遍。

+

Matt Pocock 也遇到过这个问题。他的解决方案不是"记住我说的话"，而是把这些指令打包成一个个可复用的"技能包"，像乐高积木一样按需装载。于是在 2026 年 2 月 3 日，他把自己的 .claude/skills/ 目录开源了——mattpocock/skills 诞生。

+

结果：不到 3 个月，这个仓库飙到 58k+ Stars，成为 AI 编程领域的现象级项目。

+
+ +
传统 AI 编程： Skill 化之后： +┌──────────────────┐ ┌──────────────────┐ +│ "Claude,先写测试"│ │ /tdd 一键加载 │ +│ "Claude,别推代码"│ → │ /grill-me 审需求 │ +│ "Claude,问清楚" │ │ /diagnose 修bug │ +│ 每次都重说一遍 │ │ 标准化即插即用 │ +└──────────────────┘ └──────────────────┘
+
+ + +
+

🔬 深度解析

+ +

三个核心设计问题

+

mattpocock/skills 之所以能引爆社区，是因为它精准地回答了三个问题：

+
    +
  • Q1：如何让 AI 记住大量指令而不撑爆上下文？→ 三层渐进加载
    • +
  • Q2：如何让技能包可被发现、可组合？→ SKILL.md 标准化 + npx skills 包管理器
    • +
  • Q3：如何让技能真正可复用而不是一次性提示词？→ 依赖注入模式：setup-matt-pocock-skills
    • +
+ +

架构核心：三层渐进加载 (3-Layer Loading)

+

这是整个系统的基石。Claude Code 的上下文窗口就像一间小公寓——你不能把所有东西都堆进去。

+ +
+
+flowchart TD + A["Session Init"] --> B["Layer 1"] + subgraph B["Layer 1: Discovery"] + B1["扫描 .claude/skills/*/SKILL.md"] + B2["仅加载 name + description（~100 tokens）"] + end + B --> C{"用户触发匹配？"} + C -- "否" --> D["停留在 L1，0 额外开销"] + C -- "是（如输入 /tdd）" --> E["Layer 2"] + subgraph E["Layer 2: Activation"] + E1["加载完整 SKILL.md 正文"] + E2["注入系统提示词"] + E3["~5000 tokens"] + end + E --> F{"指令中引用外部资源？"} + F -- "否" --> G["技能执行"] + F -- "是（如 references/ 目录）" --> H["Layer 3"] + subgraph H["Layer 3: Penetration"] + H1["按需读取 references/*.md"] + H2["按需执行 scripts/*.py"] + H3["可变 tokens"] + end + H --> G + G --> I["输出结果"] +
+
+ +

设计妙处：借鉴了操作系统虚拟内存的"按需分页"思想——只加载当前需要的部分。20 个技能如果全量加载需 100k tokens，分层后仅 ~2k tokens（20 × 100）。

+ +

SKILL.md 格式规范

+ 
---
+name: tdd
+description: "Red-Green-Refactor TDD 循环"
+version: "1.0.0"
+user-invocable: true
+allowed-tools: [Read, Write, Bash, Grep]
+tags: [testing, tdd, development]
+---
+
+# TDD 技能
+
+## Role Definition
+你是 TDD 驱动开发专家...
+
+## Workflow
+1. **Red** — 先写一个会失败的测试
+2. **Green** — 写最少代码让测试通过
+3. **Refactor** — 优化代码，保持绿色
+ +
+ + + + + + + + +
字段约束用途
namekebab-case，≤64字符唯一标识（也是 slash command 名）
description≤1024字符L1 加载项，技能发现用
versionsemver版本管理
user-invocableboolean是否可通过 /name 调用
allowed-tools数组运行时授予的工具权限
tags数组搜索分类
+
+ +

目录结构

+ 
.claude/skills/<skill-name>/
+├── SKILL.md              # 必需 —— 技能核心
+├── REFERENCE.md          # 可选 —— API 文档
+├── EXAMPLES.md           # 可选 —— few-shot 示例
+├── TROUBLESHOOTING.md    # 可选 —— 常见问题
+├── scripts/              # 可选 —— 可执行脚本
+├── references/           # 可选 —— 长文档
+├── templates/            # 可选 —— 输出模板
+└── resources/            # 可选 —— 数据文件
+ +

22 个技能全景

+

仓库包含约 22 个 SKILL.md 文件，覆盖 4 个大类：

+ +

工程类 (Engineering)

+
+ + + + + + + + + + + + +
技能功能设计亮点
grill-me编码前的需求追问18+ 问题穷举盲点
grill-with-docs需求追问+文档生成在 grill 基础上产出文档
tdd红绿重构 TDD 循环强制不可跳过 Red 阶段
diagnoseBug 科学排查循环假说-验证 debug 方法论
triageGitHub Issue 分类状态机驱动的标签管理
to-prd对话→PRD 生成模糊需求结构化
to-issuesPRD→GitHub Issues垂直切片拆解
improve-codebase-architecture架构改进建议渐进式改进
zoom-out代码库高空视角整体架构概览
prototype快速原型标记为"可丢弃"
+
+ +

效率类 (Productivity)

+
+ + + + + +
技能功能设计亮点
caveman压缩沟通模式减少 ~75% token 消耗
handoffAgent 间交接文档结构化的上下文移交
write-a-skill元技能——写新技能自举设计，系统可自我扩展
+
+ +

工具类 (Tooling & Setup)

+
+ + + + + + + +
技能功能
setup-matt-pocock-skills一键初始化全局配置
git-guardrails-claude-code拦截危险 git 命令
setup-pre-commitHusky + lint-staged 配置
scaffold-exercises练习目录脚手架生成
migrate-to-shoehorn测试断言迁移工具
+
+ +

核心设计模式

+ +

模式 A：依赖注入 (Dependency Injection)

+

setup-matt-pocock-skills 在首次运行时自动检测项目环境：git remote → 检测 issue tracker；已有标签 → 合并而非替换；项目类型 → 选择合适的模板。结果写入 docs/agents/ 目录下的项目配置文件。

+

类比：就像 Spring 的 IoC 容器——技能是"通用逻辑"，项目配置是"注入的依赖"。

+ +

模式 B：Grill Me 的对抗式需求澄清

+

让 AI 扮演一个"烦人的同事"，不断对你的设计方案提出质疑。不写一行代码，只提问：

+
"你考虑过边界情况吗？这个接口的调用方是谁？错误处理策略是什么？如果用户输入为空怎么办？这个方案的性能瓶颈在哪里？..."
+

为什么有效：人类在表达时容易陷入"知识的诅咒"——以为别人知道的和自己一样多。Grill Me 通过强制外化思维过程，暴露盲区。

+ +

模式 C：垂直切片 (Vertical Slicing)

+

to-issues 将 PRD 拆解为用户故事的粒度，而非技术层粒度。

+

错误方式（水平分层）：

+
    +
  • Issue 1: 写数据库模型
    • +
  • Issue 2: 写 API 接口
    • +
  • Issue 3: 写前端页面
    • +
+

正确方式（垂直切片）：

+
    +
  • Issue 1: 用户可以注册（数据库 + API + 前端）
    • +
  • Issue 2: 用户可以登录（数据库 + API + 前端）
    • +
  • Issue 3: 用户可以查看个人资料
    • +
+ +

模式 D：Git Guardrails

+

安全代理，拦截操作：git push、git reset --hard、git clean -fd。哲学：AI 执行速度快但"犯错更快"，Guardrails 是"慢下来，确保正确"的机制。

+
+ + +
+

💥 深度裂变

+ +
+
颠覆认知
+
这不是"Prompt 合集"，而是"软件工程范式转移"
+ +

大多数人对这个仓库的第一反应是："哦，一堆 Claude 提示词模板。"

+

大错特错。

+

只要仔细分析，你会发现这个仓库实际上在做三件比"提示词"深刻得多的事情：

+ +

裂变点 1：从 REPL 到 File System

+

传统的 AI 交互是 REPL（Read-Eval-Print Loop） 模式——你问一句，AI 答一句，所有状态在对话中流转。而 SKILL.md 的本质是将认知状态持久化到文件系统：

+ 
REPL 模式:        人类大脑 ←→  AI 上下文
+Skill 模式:       人类大脑 ←→  [文件系统] ←→ AI 上下文
+                  ↑__ 可检查、可版本控制、可复用 __↑
+

当 to-prd 将对话内容生成为 PRD 文件时，它不再是对话中的一段文字——它是一个可审查、可修改、可版本控制的制品。这是 AI 交互从"瞬时对话"到"工程工件"的质变。

+ +

裂变点 2：元技能——系统的自举进化

+

write-a-skill 是整座大厦的基石。它是一个写技能的技能。这意味着这套系统不需要外部维护者——AI 自己就能扩展自己的能力边界。如果你遇到一个需要新技能的场景，你不需要等 Matt Pocock 发 PR。你只需要运行 /write-a-skill，AI 就会引导你创建新的 SKILL.md，然后它立刻就能用。

+

这实际上是 Agent 领域的自举（Bootstrapping）——与编译器中"用 C 写 C 编译器"异曲同工。

+ +
🔍 搜索内化：根据 vercel-labs/skills 官方仓库及多篇技术博客验证，write-a-skill 的设计意图确实是自举（self-bootstrapping）。
+ +

裂变点 3：The Skill Economy 已现雏形

+

2026 年 4-5 月，mattpocock/skills 引爆后，社区迅速跟进了多个衍生项目：

+
+ + + + + + +
项目定位
vercel-labs/skillsnpx skills CLI 工具，成为 Skill 的"npm"
ComposioHQ/awesome-codex-skillsCodex 生态的技能集合
vinvcn/mattpocock-skills-zh-CN简体中文本地化版
vskill安全扫描增强版包管理器
+
+

最耐人寻味的是，有人已经开始在 npm 上发布 SKILL.md 包，将"认知指令"作为可分发的产品。这是一个全新的软件品类——认知包（Cognitive Packages）。

+
🔍 搜索内化：vercel-labs/skills 的 find-skills 技能安装量已超过 150 万次，多个行业来源（implicator.ai、CSDN、知乎等）交叉验证。
+
+
+ + +
+

🎯 实战指南

+ +

快速安装（1 分钟）

+ 
# 安装全部技能
+npx skills@latest add mattpocock/skills
+
+# 安装单个技能（推荐新手这样）
+npx skills@latest add mattpocock/skills --skill grill-me
+npx skills@latest add mattpocock/skills --skill tdd
+npx skills@latest add mattpocock/skills --skill git-guardrails-claude-code
+ +

初始化配置

+ 
# 在 Claude Code 中运行
+/setup-matt-pocock-skills
+ +

推荐起步三件套

+

社区公认的"最小可用组合"：

+
    +
  1. git-guardrails-claude-code → 安全锁（零成本，100% 必要）
    2. +
  2. grill-me → 需求追问（防止冲代码）
    3. +
  3. tdd → TDD 循环（保证质量）
    4. +
+ +

如何自己写 Skill

+ 
---
+name: my-custom-review
+description: "自定义代码审查技能"
+version: "1.0.0"
+user-invocable: true
+allowed-tools: [Read, Grep, Bash]
+---
+
+# 我的代码审查技能
+
+## Role
+你是一个专门审查 [XX 类型] 代码的专家。
+
+## Checklist
+1. 检查 [关注点 A]
+2. 检查 [关注点 B]
+3. 检查 [关注点 C]
+
+## Output Format
+以 Markdown 表格输出审查结果。
+ +

避坑指南

+
+ + + + + + + +
🔴 反模式✅ 正确做法
一个 SKILL.md 里塞满所有逻辑保持 SKILL.md 精简，细节放 references/
技能之间重复定义相同规则通过配置分离（docs/agents/）共享
忘记设置 allowed-tools明确声明技能需要哪些工具权限
描述太长（超 1024 字符）描述越短，L1 发现越精准
一次性写 10 个技能全装上从 3 个核心技能开始，按需增加
+
+ +

ROI 分析

+
+
+
安装
+
1 分钟 → 每个会话节省 5-10 分钟"调教"时间
+
+
+
学习
+
30 分钟熟悉 → Bug 排查效率提升 2-3 倍
+
+
+
自定义
+
1-2 小时写一个技能 → 团队标准统一
+
+
+
维护
+
npx skills update → 技能自动升级
+
+
+
+ + +
+

📝 温故知新

+ +

常见陷阱 (FAQ)

+
+ +
+ 安装后技能不生效怎么办？ +
检查是否在正确的目录下运行了 Claude Code。技能分为全局（~/.claude/skills/）和项目级（./.claude/skills/），确保安装位置正确。运行 npx skills list 查看已安装的技能。
+
+ +
+ SKILL.md 与其他 Markdown 文件的区别？ +
SKILL.md 需要 YAML 前置元数据（frontmatter），且必须有 name 和 description 字段。普通 .md 文件不会被 Claude Code 识别为技能。
+
+ +
+ 不同技能的指令冲突了怎么办？ +
Claude Code 会按技能激活顺序合并指令。如果冲突，后激活的技能不会覆盖先激活的。建议在各自 SKILL.md 中使用明确的范围限定词来避免冲突。
+
+ +
+ 可以在 Cursor / Copilot 中使用吗？ +
npx skills CLI 支持 55+ 个 Agent 平台，包括 Cursor、GitHub Copilot、Windsurf 等。但不同平台对 SKILL.md 的解析程度不同，建议在目标平台上测试。
+
+ +
+ 一个技能可以有多个文件吗？ +
可以。SKILL.md 是入口点，可以通过 scripts/ 目录引入脚本，通过 references/ 引用长文档。但 L2 激活只会加载 SKILL.md 本体。
+
+ +
+ 如何更新已安装的技能？ +
运行 npx skills@latest update。注意：有已知 bug（vercel-labs/skills#371），某些环境下 npx skills update 会静默失败，建议使用 npx skills@latest add <repo> --skill <name> -g -y 重新安装。
+
+ +
+ 技能会消耗大量 token 吗？ +
不会。L1 阶段每个技能仅消耗约 100 tokens。L2 激活后才消耗约 5000 tokens。只有 L3 会按需扩展。对比复杂任务消耗 20k+ tokens，技能的开销可忽略不计。
+
+ +
+ 这个仓库和其他 Skill 集合相比好在哪里？ +
mattpocock/skills 的核心不是"数量多"，而是"设计精良"。每个技能都遵循三层架构、渐进披露、垂直切片等设计原则，而不是简单地堆砌提示词。Matt 本人是 TypeScript 社区的核心人物，他的技能经过实际工程场景的打磨。
+
+ +
+ +

自测题

+
+
SKILL.md 的三层加载机制是哪三层？各层分别加载什么？
+
YAML 前置元数据中，哪个字段控制技能是否可通过 /name 调用？
+
垂直切片（Vertical Slicing）与水平分层拆解 Issue 的区别是什么？为什么垂直切片更好？
+
setup-matt-pocock-skills 体现了什么设计模式？它解决了什么核心问题？
+
为什么 write-a-skill 是一个"元技能"？它有什么深远意义？
+
Git Guardrails 技能解决了什么核心问题？它拦截哪些操作？
+
Grill Me 技能的本质是什么？它为什么不写代码只提问？
+
如果要在团队中推广 SKILL.md 体系，你会先推荐哪 3 个核心技能？为什么？
+
+ +

参考资源

+ +
+ +
+ +
+
+

© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过

+
+
+ + + + + diff --git a/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.md b/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.md new file mode 100644 index 0000000..5363abe --- /dev/null +++ b/knowledge/entries/knowledge_20260518_mattpocock_skills/knowledge_20260518_mattpocock_skills.md @@ -0,0 +1,440 @@ +--- +title: "mattpocock/skills 深度解析：AI Agent 工作流的工程化革命" +author: "叫我小杨同学的小码酱" +tags: [Claude Code, Agent Skills, AI Engineering, Workflow, Matt Pocock, SKILL.md] +created: 2026-05-18 +--- + +# mattpocock/skills 深度解析：AI Agent 工作流的工程化革命 + +--- + +## 模块 0：核心摘要 (TL;DR) + +> **一句话核心**：Matt Pocock 将自己在 Claude Code 中打磨了数月的 AI 协作工作流，打包成可复用、可组合的 SKILL.md 技能包，开启了"AI 技能包管理"的工程化时代。 + +**认知挂钩**：就像 jQuery 插件让前端开发从"每次都从头写 JS"进化到"装个插件就行"，mattpocock/skills 让 AI 编程从"每次都从头调教 AI"进化到"装个 Skill 就行"——它定义了 AI Agent 指令的封装标准。 + +**真理锚点**：*"Skills for Real Engineers. Straight from my .claude directory."* —— Matt Pocock + +--- + +## 模块 1：概念破冰 (Concept Ice-breaking) + +### 巧记卡片 + +``` +AI 编程三板斧： +一装技能包，行为有 template（模板化） +二写 SKILL.md，流程有 blueprint（蓝图化） +三用 npx skills，分发有 package（工程化） +``` + +### 故事引入 + +想象一下：你新招了一个能力超强的实习生 Claude。每次让他写代码，你都得花 20 分钟交代一遍："先写测试、再实现、再重构。不要直接改代码，先问我。Git push 之前必须确认。" + +一个月后你崩溃了——**每次对话都要重新教一遍**。 + +Matt Pocock 也遇到过这个问题。他的解决方案不是"记住我说的话"，而是**把这些指令打包成一个个可复用的"技能包"**，像乐高积木一样按需装载。于是在2026年2月3日，他把自己的 `.claude/skills/` 目录开源了——mattpocock/skills 诞生。 + +**结果**：不到 3 个月，这个仓库飙到 58k+ Stars，成为 AI 编程领域的现象级项目。 + +### 可视化 + +``` +传统 AI 编程： Skill 化之后： +┌──────────────────┐ ┌──────────────────┐ +│ "Claude,先写测试"│ │ /tdd 一键加载 │ +│ "Claude,别推代码"│ → │ /grill-me 审需求 │ +│ "Claude,问清楚" │ │ /diagnose 修bug │ +│ 每次都重说一遍 │ │ 标准化即插即用 │ +└──────────────────┘ └──────────────────┘ +``` + +--- + +## 模块 2：深度解析 (Deep Analysis) + +### 2.1 三个核心设计问题 + +Matt Pocock 的 skills 仓库之所以能引爆社区，是因为它精准地回答了三个问题： + +**Q1: 如何让 AI 记住大量指令而不撑爆上下文？** +→ **三层渐进加载 (Progressive 3-Layer Loading)** + +**Q2: 如何让技能包可被发现、可组合？** +→ **SKILL.md 标准化 + npx skills 包管理器** + +**Q3: 如何让技能真正可复用而不是一次性提示词？** +→ **依赖注入模式：setup-matt-pocock-skills** + +### 2.2 架构核心：三层渐进加载 (3-Layer Loading) + +这是整个系统的基石。Claude Code 的上下文窗口就像一间小公寓——你不能把所有东西都堆进去。 + +```mermaid +flowchart TD + A["Session Init"] --> B["Layer 1"] + subgraph B["Layer 1: Discovery"] + B1["扫描 .claude/skills/*/SKILL.md"] + B2["仅加载 name + description（~100 tokens）"] + end + B --> C{"用户触发匹配？"} + C -- "否" --> D["停留在 L1，0 额外开销"] + C -- "是（如输入 /tdd）" --> E["Layer 2"] + subgraph E["Layer 2: Activation"] + E1["加载完整 SKILL.md 正文"] + E2["注入系统提示词"] + E3["~5000 tokens"] + end + E --> F{"指令中引用外部资源？"} + F -- "否" --> G["技能执行"] + F -- "是（如 references/ 目录）" --> H["Layer 3"] + subgraph H["Layer 3: Penetration"] + H1["按需读取 references/*.md"] + H2["按需执行 scripts/*.py"] + H3["可变 tokens"] + end + H --> G + G --> I["输出结果"] +``` + +**设计妙处**：这个机制借鉴了操作系统虚拟内存的"按需分页"思想——只加载当前需要的部分，极大节省了上下文空间。如果你有 20 个技能，每个占 5000 tokens，一次性加载就是 100k tokens。但有了分层设计，实际消耗仅 2k tokens 左右（20 × 100 = 2000）。 + +### 2.3 SKILL.md 格式规范 + +每个技能的核心是一个 Markdown 文件，带 YAML 前置元数据： + +```markdown +--- +name: tdd +description: "Red-Green-Refactor TDD 循环" +version: "1.0.0" +user-invocable: true +allowed-tools: [Read, Write, Bash, Grep] +tags: [testing, tdd, development] +--- + +# TDD 技能 + +## Role Definition +你是 TDD 驱动开发专家... + +## Workflow +1. **Red** — 先写一个会失败的测试 +2. **Green** — 写最少代码让测试通过 +3. **Refactor** — 优化代码，保持绿色 + +## Constraints +- 严禁跳过 Red 阶段 +- 每次重构后运行全部测试 +``` + +**YAML 字段详解**： + +| 字段 | 约束 | 用途 | +|------|------|------| +| `name` | kebab-case，≤64字符 | 唯一标识（也是 slash command 名） | +| `description` | ≤1024字符 | L1 加载项，技能发现用 | +| `version` | semver | 版本管理 | +| `user-invocable` | boolean | 是否可通过 `/name` 调用 | +| `allowed-tools` | 数组 | 技能运行时授予的工具权限 | +| `tags` | 数组 | 用于搜索分类 | + +### 2.4 目录结构 + +``` +.claude/skills// +├── SKILL.md # 必需 —— 技能的核心 +├── REFERENCE.md # 可选 —— API 文档、规则 +├── EXAMPLES.md # 可选 —— few-shot 示例 +├── TROUBLESHOOTING.md # 可选 —— 常见问题 +├── scripts/ # 可选 —— 可执行脚本 +│ ├── process.py +│ └── utils.js +├── references/ # 可选 —— 长文档 +│ └── style-guide.md +├── templates/ # 可选 —— 输出模板 +│ └── report-template.txt +└── resources/ # 可选 —— 数据文件 + └── template.xlsx +``` + +**渐进披露的精髓**：`SKILL.md` 保持足够短（<5000 tokens），只写核心流程。所有长文档放在 `references/`，仅在需要时由 `SKILL.md` 中的指令触发加载。这样既保证了功能的完整性，又维持了上下文的轻量。 + +### 2.5 22 个技能全景 + +Matt Pocock 的仓库包含约 22 个 SKILL.md 文件，覆盖 4 个大类： + +#### 工程类 (Engineering) +| 技能 | 功能 | 设计亮点 | +|------|------|---------| +| **grill-me** | 编码前的需求追问 | 18+ 问题穷举盲点，不写代码只提问 | +| **grill-with-docs** | 需求追问+文档生成 | 在 grill 基础上产出文档产物 | +| **tdd** | 红绿重构 TDD 循环 | 强制不可跳过 Red 阶段 | +| **diagnose** | Bug 科学排查循环 | 基于假说-验证的 debug 方法论 | +| **triage** | GitHub Issue 分类 | 状态机驱动的标签化管理 | +| **to-prd** | 对话→PRD 生成 | 将模糊需求转化为结构化的 PRD | +| **to-issues** | PRD→GitHub Issues | 垂直切片拆解，而非分层拆解 | +| **improve-codebase-architecture** | 架构改进建议 | 识别技术债并提出渐进式改进 | +| **zoom-out** | 代码库高空视角 | 整体架构概览，不漏细节 | +| **prototype** | 快速原型 | 明确标记为"可丢弃" | + +#### 效率类 (Productivity) +| 技能 | 功能 | 设计亮点 | +|------|------|---------| +| **caveman** | 压缩沟通模式 | 减少约 75% token 消耗的极简回复 | +| **handoff** | Agent 间交接文档 | 结构化的上下文移交格式 | +| **write-a-skill** | 元技能——写新技能 | 自举设计，系统可自我扩展 | + +#### 工具类 (Tooling & Setup) +| 技能 | 功能 | +|------|------| +| **setup-matt-pocock-skills** | 一键初始化全局配置 | +| **git-guardrails-claude-code** | 拦截危险 git 命令 | +| **setup-pre-commit** | Husky + lint-staged 配置 | +| **scaffold-exercises** | 练习目录脚手架生成 | +| **migrate-to-shoehorn** | 测试断言迁移工具 | + +### 2.6 核心设计模式 + +#### 模式 A: 依赖注入 (Dependency Injection) +`setup-matt-pocock-skills` 在首次运行时，自动检测项目环境： +- git remote → 检测 issue tracker +- 已有标签 → 合并，而非替换 +- 项目类型 → 选择合适的模板 + +结果写入 `docs/agents/` 目录下的项目配置文件。 + +**类比**：就像 Spring 的 IoC 容器——技能是"通用逻辑"，项目配置是"注入的依赖"。 + +#### 模式 B: Grill Me 的对抗式需求澄清 +这是一个反直觉的设计——**让 AI 扮演一个"烦人的同事"**，不断对你的设计方案提出质疑。它不写一行代码，只提问： + +> "你考虑过边界情况吗？这个接口的调用方是谁？错误处理策略是什么？如果用户输入为空怎么办？这个方案的性能瓶颈在哪里？..." + +**为什么有效**：人类在表达时容易陷入"知识的诅咒"——以为别人知道的和自己一样多。Grill Me 通过强制外化思维过程，暴露了那些"你以为想清楚了但其实没有"的盲区。 + +#### 模式 C: 垂直切片 (Vertical Slicing) +`to-issues` 将 PRD 拆解为用户故事的粒度，而非技术层粒度。 + +**错误方式**（水平分层）： +- Issue 1: 写数据库模型 +- Issue 2: 写 API 接口 +- Issue 3: 写前端页面 + +**正确方式**（垂直切片）： +- Issue 1: 用户可以注册（数据库 + API + 前端） +- Issue 2: 用户可以登录（数据库 + API + 前端） +- Issue 3: 用户可以查看个人资料 + +**原因**：每个垂直切片都是**可独立交付**的——开发完一个就真正能用，而不是"所有模型都写完了但啥也看不到"。 + +#### 模式 D: Git Guardrails +这个技能本质上是一个**安全代理**，它拦截以下操作： +- `git push` → 要求先拉取最新代码 +- `git reset --hard` → 要求显示将被丢弃的变更 +- `git clean -fd` → 需要明确确认 + +**哲学**：AI 执行速度很快，但快意味着"犯错更快"。Guardrails 是"慢下来，确保正确"的机制。 + +--- + +## 模块 3：深度裂变 (Deep Fission) + +### 🔍 颠覆认知：这不是"Prompt 合集"，而是"软件工程范式转移" + +大多数人对这个仓库的第一反应是："哦，一堆 Claude 提示词模板。" + +**大错特错。** + +只要仔细分析，你会发现这个仓库实际上在做三件比"提示词"深刻得多的事情： + +#### 裂变点 1: 从 REPL 到 File System + +传统的 AI 交互是 **REPL（Read-Eval-Print Loop）** 模式——你问一句，AI 答一句，所有状态在对话中流转。而 SKILL.md 的本质是将认知状态**持久化到文件系统**： + +``` +REPL 模式: 人类大脑 ←→ AI 上下文 +Skill 模式: 人类大脑 ←→ [文件系统] ←→ AI 上下文 + ↑__ 可检查、可版本控制、可复用 __↑ +``` + +当 `to-prd` 将对话内容生成为 PRD 文件时，它不再是对话中的一段文字——它是一个可审查、可修改、可版本控制的**制品**。这是 AI 交互从"瞬时对话"到"工程工件"的质变。 + +#### 裂变点 2: 元技能——系统的自举进化 + +`write-a-skill` 是整座大厦的基石。它是一个**写技能的技能**。这意味着： + +> 这套系统不需要外部维护者——AI 自己就能扩展自己的能力边界。 + +如果你遇到一个需要新技能的场景，你不需要等 Matt Pocock 发 PR。你只需要运行 `/write-a-skill`，AI 就会引导你创建新的 SKILL.md，然后它立刻就能用。这实际上是 Agent 领域的**自举（Bootstrapping）**——与编译器中"用 C 写 C 编译器"异曲同工。 + +#### 裂变点 3: The Skill Economy 已现雏形 + +2026 年 4-5 月，mattpocock/skills 引爆后，社区迅速跟进了多个衍生项目： + +| 项目 | 定位 | +|------|------| +| **vercel-labs/skills** | `npx skills` CLI 工具，成为 Skill 的"npm" | +| **ComposioHQ/awesome-codex-skills** | Codex 生态的技能集合 | +| **vinvcn/mattpocock-skills-zh-CN** | 简体中文本地化版 | +| **vskill** | 安全扫描增强版包管理器 | + +最耐人寻味的是，有人已经开始在 **npm 上发布 SKILL.md 包**，将"认知指令"作为一种可分发的产品。这是一个全新的软件品类——**认知包 (Cognitive Packages)**。 + +🔍 **搜索内化**：根据多个来源验证，vercel-labs/skills 的 `find-skills` 技能安装量已超过 150 万次，头部技能的安装量达到了数十万级别。这已经不仅仅是"开发者玩具"的规模。 + +--- + +## 模块 4：实战指南 (Actionable Guide) + +### 4.1 如何开始 + +#### 快速安装（1 分钟） + +```bash +# 安装全部技能 +npx skills@latest add mattpocock/skills + +# 安装单个技能（推荐新手这样） +npx skills@latest add mattpocock/skills --skill grill-me +npx skills@latest add mattpocock/skills --skill tdd +npx skills@latest add mattpocock/skills --skill git-guardrails-claude-code +``` + +#### 初始化配置 + +```bash +# 在 Claude Code 中运行 +/setup-matt-pocock-skills +``` + +该命令会自动： +1. 检测你的 git remote +2. 设置 issue tracker 配置 +3. 初始化 `docs/agents/` 目录 + +### 4.2 推荐起步三件套 + +社区公认的"最小可用组合"： + +``` +1. git-guardrails-claude-code → 安全锁（零成本，100% 必要） +2. grill-me → 需求追问（防止冲代码） +3. tdd → TDD 循环（保证质量） +``` + +### 4.3 如何自己写 Skill + +参考 `/write-a-skill` 的引导流程： + +```markdown +--- +name: my-custom-review +description: "自定义代码审查技能" +version: "1.0.0" +user-invocable: true +allowed-tools: [Read, Grep, Bash] +--- + +# 我的代码审查技能 + +## Role +你是一个专门审查 [XX 类型] 代码的专家。 + +## Checklist +1. 检查 [关注点 A] +2. 检查 [关注点 B] +3. 检查 [关注点 C] + +## Output Format +以 Markdown 表格输出审查结果。 +``` + +### 4.4 避坑指南 + +| 🔴 反模式 | ✅ 正确做法 | +|-----------|-----------| +| 一个 SKILL.md 里塞满所有逻辑 | 保持 SKILL.md 精简，细节放 references/ | +| 技能之间重复定义相同规则 | 通过配置分离（`docs/agents/`）共享 | +| 忘记设置 `allowed-tools` | 明确声明技能需要哪些工具权限 | +| 描述太长（超 1024 字符） | 描述越短，L1 发现越精准 | +| 一次性写 10 个技能全装上 | 从 3 个核心技能开始，按需增加 | + +### 4.5 ROI 分析 + +| 投入 | 产出 | +|------|------| +| 安装：1 分钟 | 每个会话节省 5-10 分钟"调教"时间 | +| 学习：30 分钟熟悉各技能 | Bug 排查效率提升 2-3 倍 | +| 自定义：1-2 小时写一个技能 | 团队标准统一，新人上手更快 | + +--- + +## 模块 5：温故知新 (Consolidation) + +### 常见陷阱 (FAQ) + +
+Q: 安装后技能不生效怎么办？ +检查是否在正确的目录下运行了 Claude Code。技能分为全局（`~/.claude/skills/`）和项目级（`./.claude/skills/`），确保安装位置正确。运行 `npx skills list` 查看已安装的技能。 +
+ +
+Q: SKILL.md 与其他 Markdown 文件的区别？ +SKILL.md 需要 YAML 前置元数据（frontmatter），且必须有 `name` 和 `description` 字段。普通 .md 文件不会被 Claude Code 识别为技能。 +
+ +
+Q: 不同技能的指令冲突了怎么办？ +Claude Code 会按技能激活顺序合并指令。如果冲突，后激活的技能不会覆盖先激活的。建议在各自 SKILL.md 中使用明确的范围限定词（比如"/diagnose 场景下"）来避免冲突。 +
+ +
+Q: 可以在 Cursor / Copilot 中使用吗？ +`npx skills` CLI 支持 55+ 个 Agent 平台，包括 Cursor、GitHub Copilot、Windsurf 等。但不同平台对 SKILL.md 的解析程度不同，建议在目标平台上测试。 +
+ +
+Q: 一个技能可以有多个文件吗？ +可以。SKILL.md 是入口点，可以通过 `scripts/` 目录引入脚本，通过 `references/` 引用长文档。但 L2 激活只会加载 SKILL.md 本体。 +
+ +
+Q: 如何更新已安装的技能？ +运行 `npx skills@latest update`。注意：目前有一个已知 bug（vercel-labs/skills#371），某些环境下 `npx skills update` 会静默失败，建议使用 `npx skills@latest add --skill -g -y` 重新安装。 +
+ +
+Q: 技能会消耗大量 token 吗？ +不会。L1 阶段每个技能仅消耗约 100 tokens。L2 激活后才消耗约 5000 tokens。只有 L3 会按需扩展。对比一个复杂的任务可能消耗 20k+ tokens，技能的开销可以忽略不计。 +
+ +
+Q: 这个仓库和其他 Skill 集合相比好在哪里？ +mattpocock/skills 的核心不是"数量多"，而是"设计精良"。每个技能都遵循三层架构、渐进披露、垂直切片等设计原则，而不是简单地堆砌提示词。Matt 本人是 TypeScript 社区的核心人物，他的技能经过实际工程场景的打磨。 +
+ +### 自测题 + +1. **SKILL.md 的三层加载机制是哪三层？各层分别加载什么？** +2. **YAML 前置元数据中，哪个字段控制技能是否可通过 `/name` 调用？** +3. **垂直切片（Vertical Slicing）与水平分层拆解 Issue 的区别是什么？为什么垂直切片更好？** +4. **`setup-matt-pocock-skills` 体现了什么设计模式？它解决了什么核心问题？** +5. **为什么 `write-a-skill` 是一个"元技能"？它有什么深远意义？** +6. **Git Guardrails 技能解决了什么核心问题？它拦截哪些操作？** +7. **Grill Me 技能的本质是什么？它为什么不写代码只提问？** +8. **如果要在团队中推广 SKILL.md 体系，你会先推荐哪 3 个核心技能？为什么？** + +### 参考资源 + +- GitHub 仓库：https://github.com/mattpocock/skills +- Vercel Labs Skills CLI：https://github.com/vercel-labs/skills +- 中文翻译版：https://github.com/vinvcn/mattpocock-skills-zh-CN +- 搜索安装：在 Claude Code 中运行 `/find-skills` + +--- + +*© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过* diff --git a/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.html b/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.html new file mode 100644 index 0000000..296a1b9 --- /dev/null +++ b/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.html @@ -0,0 +1,370 @@ + + + + + +CodeStable 深度解析 — github-learn + + + + + +
+
+

CodeStable 深度解析：编排软件生命周期，而非编排 Agent

+
叫我小杨同学的小码酱2026-05-19
+
+CodeStableAI EngineeringAgent SkillsHarness EngineeringHuman-in-the-Loop工作流 +
+
+
+ +
+ + + +
+

📌 核心摘要

+
+

CodeStable 是首个将 AI 编码工作流的建模对象从"Agent 怎么协作"翻转为"软件要素怎么组织"的框架——它管的不再是 Agent，而是需求、架构、特性、问题、知识这六个实体的完整生命周期。

+
认知挂钩：想象你在管一个图书馆。SuperPowers 和 OpenSpec 在优化"管理员怎么工作得更高效"。CodeStable 在问一个更根本的问题——书有没有被正确分类、编目、放在对的书架上？管理员再高效，书是乱的，三年后谁也找不到东西。CodeStable 就是那个图书分类法。
+
真理锚点："软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好。" —— liuzhengdong
+
+
+ +
+

🧊 概念破冰

+ +
AI 框架两派分： +Agent 编排派 → 管的是"谁干什么、怎么配合" +软件要素派 → 管的是"需求架构特性问题知识，每样都放对位置" + +CodeStable 选了后者。记住6+3： +6 实体（Req, Arch, Roadmap, Feature, Issue, Compound） +3 流程（特性引入、问题修复、代码重构）
+ +
+
📖 故事引入
+

2026 年初，开发者 liuzhengdong 正在开发一套新的 Harness Agent。一开始他用 VibeCoding——只写设计和需求，代码由 AI 改。这样撑了大部分特性开发。

+

直到有一天，Codex 反复解决不了一个"他认为比较简单"的问题，反复在同一个地方犯错。

+

他意识到：项目变大了，AI 开始迷失。不是因为 AI 不够聪明，而是因为之前的那些需求、设计决策、架构约束全忘了——这些信息散落在对话历史里，每次都丢失。

+

他调研了 OpenSpec、SuperPowers、Oh-My-OpenAgent，没一个让他满意。于是从零写了 CodeStable。2026 年 4 月发布，不到两个月，781 stars。

+
+ +
Agent 编排派（SuperPowers / OpenSpec / OMO）: + ┌─────┐ ┌─────┐ ┌─────┐ + │Agent1│←→│Agent2│←→│Agent3│ ← 编排的是 Agent + └─────┘ └─────┘ └─────┘ + ↓ ↓ ↓ + [代码] [代码] [代码] ← 软件要素在对话中丢失 + +软件要素派（CodeStable）: + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │Requirement│ │Architecture│ │ Feature │ ← 编排的是软件要素 + └──────────┘ └──────────┘ └──────────┘ + ↑ ↑ ↑ + └────────────┼────────────┘ + │ + [Agent 们] ← Agent 是执行体，不是建模对象 + │ + codestable/ ← 所有产物持久化在文件系统
+
+ +
+

🔬 深度解析

+ +

哲学内核：为什么"人在环"不是弱点而是设计选择

+

CodeStable 最受争议的点，也是它与主流框架最根本的分歧：它认为程序员必须是"在环对象"。

+

2026 年 2 月，Hashicorp 联合创始人 Mitchell Hashimoto 提出了 Harness Engineering（驾驭工程） 概念——"人类掌舵，Agent 执行"。CodeStable 是这一范式在"编码工作流"领域的具体实现。

+

它不反对自动化。它反对的是不留下痕迹的自动化。当 AI 自主完成一个 feature 后，三个月后另一个 developer 面对这段代码时，为什么这么设计？当时有哪些备选方案？这些设计依赖了什么约束？——全部丢失了。

+

CodeStable 的回答：每做一个决定，就在 codestable/ 目录里写下来。 给人读的，不是给 AI 自嗨的。

+ +

6 个实体 + 3 个流程

+ +
+
+flowchart TD + CS["cs 根入口"] --> ONBOARD["cs-onboard 初始化"] + ONBOARD --> REQ["cs-req: 需求实体"] + ONBOARD --> ARCH["cs-arch: 架构实体"] + REQ --> ROADMAP["cs-roadmap: 路线图实体"] + ARCH --> ROADMAP + ROADMAP --> FEAT["cs-feat: 特性流程"] + ROADMAP --> ISSUE["cs-issue: 问题流程"] + ROADMAP --> REFACTOR["cs-refactor: 重构流程"] + FEAT --> FEAT_D["cs-feat-design"] + FEAT_D --> FEAT_I["cs-feat-impl"] + FEAT_I --> FEAT_A["cs-feat-accept"] + ISSUE --> ISSUE_R["cs-issue-report"] + ISSUE_R --> ISSUE_A["cs-issue-analyze"] + ISSUE_A --> ISSUE_F["cs-issue-fix"] + FEAT_A --> COMPOUND["compound: 知识沉淀"] + ISSUE_F --> COMPOUND + REFACTOR --> COMPOUND + COMPOUND --> LEARN["cs-learn: 经验"] + COMPOUND --> TRICK["cs-trick: 模式"] + COMPOUND --> DECIDE["cs-decide: 决策"] + COMPOUND --> EXPLORE["cs-explore: 探索"] + LEARN -. "下次被检索" .-> ARCH + TRICK -. "下次被检索" .-> FEAT_D + DECIDE -. "下次被检索" .-> ISSUE_A + EXPLORE -. "下次被检索" .-> ROADMAP +
+
+ +
+ + + + + + + + +
实体英文核心用途
需求requirements原始用户故事、讨论与权衡。代码烂掉时最终的逃生通道
架构architecture系统编排层文档，精简统一，给人读的
路线图roadmap大需求拆解——模块拆分 + 接口契约 + 子 feature 清单
特性feature实际工程执行，design → impl → accept 三步闭环
问题issueBug 单，report → analyze → fix，analyze 和 fix 强制分离
知识compound复利工程：经验 / 模式 / 决策 / 探索，四种知识类型
+
+ +

分层架构：不是流水线，是"分层 + 事件驱动"

+ +
+ + + + + + + + +
层内容触发时机
阶段 0cs-onboard 初始化骨架新项目接入（一次）
第 1 层cs-req / cs-arch 长效档案需求/架构变更（反复刷新）
第 2 层cs-roadmap 规划大需求拆解（按需进入）
讨论入口cs-brainstorm 分诊想法模糊时（可选）
第 3 层cs-feat-* / cs-issue-* / cs-refactor-*事件驱动
横切层cs-learn / cs-trick / cs-decide / cs-explore任意时刻觉得"值得记下来"
+
+ +

运行时结构：codestable/ 目录设计

+
你的项目/
+├── codestable/
+│   ├── requirements/              # 需求（"为什么要有这个能力"）
+│   ├── architecture/              # 架构（"用什么结构实现"）
+│   ├── roadmap/                   # 路线图（"接下来怎么走"）
+│   ├── features/YYYY-MM-DD-{slug}/ # 特性执行
+│   ├── issues/YYYY-MM-DD-{slug}/  # 问题修复
+│   ├── refactors/YYYY-MM-DD-{slug}/ # 重构（beta）
+│   ├── compound/                  # 知识沉淀（复利工程）
+│   │   └── YYYY-MM-DD-{type}-{slug}.md
+│   ├── tools/                     # 共享脚本
+│   └── reference/                 # 共享参考文档
+└── AGENTS.md
+ +

硬约束：Skill 隔离与依赖注入

+

每个 skill 运行时只能看到自己包内的文件。跨 skill 共享的文档由 cs-onboard 从技能包复制到项目的 codestable/reference/，其他 skill 通过项目相对路径读取。这本质上是一个依赖注入模式——skill 是通用逻辑，codestable/ 是注入的运行时上下文。

+
+ +
+

💥 深度裂变

+ +
+
颠覆认知
+
"编排软件要素"是真的范式创新，还是旧酒新瓶？
+ +

对 CodeStable 最尖锐的批判性审视。

+ +

正方：确实在范式层面做了翻转

+

所有主流 AI 编码框架都在"Agent 编排"范式下工作。CodeStable 问的是另一个问题：软件的需求、约束、决策怎么被记下来、被检索、被复用？

+

实践后果：知识沉淀从"副作用"变成"一等公民"。SuperPowers 跑完 TDD → 得到代码和测试。CodeStable 跑完 feature → 得到代码 + design + acceptance + compound。后者在"三个月后还能被理解"上有结构性优势。

+ +

反方：四个没有解决的问题

+
    +
  1. 知识检索依赖 AI 上下文窗口：compound/ 积累 200 个文件后，AI 能一次读完吗？没有索引或向量检索。
    2. +
  2. 没有强制执行机制：SuperPowers 的 TDD 是铁律，CodeStable 的 accept 执行深度取决于人。人把关不严，质量门形同虚设。
    3. +
  3. cs-brainstorm 的分诊能力受限：让 AI 判断模糊想法"该走哪个流程"，这个判断本身就需要很高的理解力。
    4. +
  4. 对竞品的批评不完全公平：OpenSpec 的 Spec 文件设计目标就是人机双读。很多用户的实际体验并非"人类没法读"。
    5. +
+ +
🔍 搜索内化：V2EX 和 LINUX DO 社区反馈——"正确性对我来说够了，按照流程生成完手动审查，不复杂的需求基本一次性搞定"——但也指出"上下文一长就会忘"的知识检索问题。作者在 Roadmap 中坦承多个模块仍在 beta。
+ +

一个被忽略的关键信号：CodeStable 承认自己会"过时"

+
"CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。"
+

这让它区别于绝大多数 AI 框架——不是试图建立永恒的体系，而是承认自己是过渡性工具。这种"自我消解的诚实"在 AI 工具领域极为罕见。

+
+
+ +
+

🎯 实战指南

+ +

快速开始

+
# 安装
+npx skills add https://github.com/liuzhengdongfortest/CodeStable
+
+# 初始化项目
+/cs-onboard
+
+# 日常使用——不知道用哪个就喊根入口
+/cs
+ +

典型工作流

+
# 场景 A：新增功能
+/cs-feat → /cs-feat-design → /cs-feat-impl → /cs-feat-accept
+
+# 场景 B：修 Bug
+/cs-issue → /cs-issue-report → /cs-issue-analyze → /cs-issue-fix
+
+# 场景 C：快速小改动
+/cs-feat-ff    # 超轻量通道
+
+# 场景 D：沉淀知识
+/cs-learn      # 踩坑经验
+/cs-trick      # 可复用模式
+/cs-decide     # 技术决策
+ +

避坑指南

+
+ + + + + + + +
🔴 反模式✅ 正确做法
跳过 cs-onboard，手动创建 codestable/必须用 cs-onboard 初始化，确保 reference/ 被正确复制
cs-feat-impl 中不看 design 自己脑补design 是唯一输入，偏离 design 必须回退更新 design
所有改动都走 cs-feat（太重）小改动用 cs-feat-ff，大功能走完整流程
compound 文件乱命名严格遵循 YYYY-MM-DD-{type}-{slug}.md 格式
不写 acceptance 报告acceptance 报告是"三个月后能理解"的关键
+
+ +

CodeStable 与你现有 dev-flow 的融合点

+
+ + + + + + + + +
dev-flow 阶段CodeStable 替代/增强
Phase 0 初始 PRDcs-req 沉淀为需求文档（更持久）
Phase 1.5 结构化 PRDcs-feat-design 作为 design 文档
Phase 2 grill-with-docscs-brainstorm 作为讨论入口
Phase 2.5 zoom-outcs-arch 单独维护架构文档
Phase 3 执行cs-feat-impl + cs-feat-accept
Phase 4 收尾cs-learn / cs-decide 沉淀知识
+
+ +

ROI 分析

+
+
初始化
cs-onboard 2 分钟 → 建好所有目录骨架
+
Feature 流程
比 OpenSpec 多 5-10 分钟 → 留下 design + acceptance + compound
+
学习成本
30-45 分钟熟悉 22 技能 → 覆盖完整软件生命周期
+
长期收益
3 个月后 feature 设计可回溯 → 消除隐知识丢失
+
+
+ +
+

📝 温故知新

+ +

FAQ

+
+
CodeStable 和 dev-flow 谁更好？
不是替代关系。dev-flow 是流程编排元技能，CodeStable 是软件生命周期建模体系。可组合使用：dev-flow 的 grill-with-docs 补充 CodeStable 缺少的术语对齐；CodeStable 的 compound 补充 dev-flow 缺少的结构化知识沉淀。
+
CodeStable 适合一个人用吗？
非常适合。设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作。如果是一个人维护的长期项目，CodeStable 是目前最合适的框架。
+
CodeStable 和 SuperPowers 能一起用吗？
理论上可以，但不推荐。哲学对立——SuperPowers 希望人少介入，CodeStable 要求人在环。建议根据项目类型选一个主线。
+
codestable/ 目录会变得很臃肿吗？
会，这是有意为之。"臃肿"的文档目录好过"干净"的失忆。日期前缀使按时间浏览很自然，compound 通过 type 字段做聚合。
+
轻量通道 cs-feat-ff 什么时候用？
非常明确的小改动——"把按钮颜色改蓝"、"加一个表单字段"。不确定该不该走 ff，就走完整流程。
+
如果不想用全部 22 个技能怎么办？
技能是松耦合的。最精简子集：cs-onboard + cs-req + cs-feat + cs-issue。
+
知识检索能力有多强？
目前是"文件命名约定 + AI 选择性读取"，非向量语义检索。compound/ 积累 50+ 文件后需要引导 AI 只读相关的。
+
和 mattpocock/skills 的关系？
同样 Skills 封装形式，建模哲学不同。mattpocock 是"小工具"——每个解决特定问题。CodeStable 是"体系"——每个是软件生命周期中的一个步骤。
+
+ +

自测题

+
+
CodeStable 的 6 个软件实体是哪 6 个？每个的核心用途是什么？
+
"编排 Agent"和"编排软件要素"的根本区别是什么？在工程实践上会产生什么不同的后果？
+
CodeStable 的 3 个核心流程分别是什么？每个流程的技能链是什么？
+
cs-feat-design 为什么被设计为"后续所有步骤的唯一输入"？这种设计避免了什么问题？
+
compound/ 目录下的 4 种知识类型分别是什么？它们会在什么时机被 AI 重新检索？
+
CodeStable 为什么要求每个 skill 运行时只能看到自己包内的文件？这个硬约束解决了什么问题？
+
CodeStable 作者所说的"复利工程"（Compound Engineering）具体指什么？
+
如果你要将 CodeStable 集成到你现有的 dev-flow 中，哪些 Phase 可以保留、哪些可以用 CodeStable 替换？
+
+ +

参考资源

+ +
+ +
+ +
+

© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过

+
+ + + + diff --git a/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.md b/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.md new file mode 100644 index 0000000..8f541f2 --- /dev/null +++ b/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.md @@ -0,0 +1,378 @@ +--- +title: "CodeStable 深度解析：编排软件生命周期，而非编排 Agent" +author: "叫我小杨同学的小码酱" +tags: [CodeStable, AI Engineering, Agent Skills, Harness Engineering, Human-in-the-Loop, OpenSpec, SuperPowers, 工作流] +created: 2026-05-19 +--- + +# CodeStable 深度解析：编排软件生命周期，而非编排 Agent + +--- + +## 模块 0：核心摘要 (TL;DR) + +> **一句话核心**：CodeStable 是首个将 AI 编码工作流的建模对象从"Agent 怎么协作"翻转为"软件要素怎么组织"的框架——它管的不再是 Agent，而是需求、架构、特性、问题、知识这六个实体的完整生命周期。 + +**认知挂钩**：想象你在管一个图书馆。SuperPowers 和 OpenSpec 在优化"管理员怎么工作得更高效"。CodeStable 在问一个更根本的问题——**书有没有被正确分类、编目、放在对的书架上**？管理员再高效，书是乱的，三年后谁也找不到东西。CodeStable 就是那个图书分类法。 + +**真理锚点**：*"软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好。"* —— liuzhengdong，CodeStable 作者 + +--- + +## 模块 1：概念破冰 (Concept Ice-breaking) + +### 巧记卡片 + +``` +AI 框架两派分： +Agent 编排派 → 管的是"谁干什么、怎么配合" +软件要素派 → 管的是"需求架构特性问题知识，每样都放对位置" + +CodeStable 选了后者。记住6+3： +6 实体（Req, Arch, Roadmap, Feature, Issue, Compound） +3 流程（特性引入、问题修复、代码重构） +``` + +### 故事引入 + +2026 年初，开发者 liuzhengdong 正在开发一套新的 Harness Agent（项目代号 MA）。一开始他用 VibeCoding——只写设计和需求，代码由 AI 改。这样撑了大部分特性开发。 + +直到有一天，Codex 反复解决不了一个"他认为比较简单"的问题，**反复在同一个地方犯错**。 + +他意识到：项目变大了，AI 开始迷失。不是因为 AI 不够聪明，而是因为**之前的那些需求、设计决策、架构约束，AI 全忘了**——或者更准确地说，这些信息散落在对话历史里，每次都丢失。 + +他调研了市面上所有的 AI 编码框架——OpenSpec、SuperPowers、Oh-My-OpenAgent——没一个让他满意： + +- OpenSpec "太简单，生成的 Spec 抽象到人类没法读" +- SuperPowers "没有流程约束，不知道该用哪个" +- Oh-My-OpenAgent "太重，且哲学上认为'人介入 = 失败'" + +于是他决定从零写一套新的。2026 年 4 月，CodeStable 诞生。不到两个月，781 stars。 + +### 可视化：两种范式的根本差异 + +``` +Agent 编排派（SuperPowers / OpenSpec / OMO）: + ┌─────┐ ┌─────┐ ┌─────┐ + │Agent1│←→│Agent2│←→│Agent3│ ← 编排的是 Agent + └─────┘ └─────┘ └─────┘ + ↓ ↓ ↓ + [代码] [代码] [代码] ← 软件要素在对话中丢失 + +软件要素派（CodeStable）: + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │Requirement│ │Architecture│ │ Feature │ ← 编排的是软件要素 + └──────────┘ └──────────┘ └──────────┘ + ↑ ↑ ↑ + └────────────┼────────────┘ + │ + [Agent 们] ← Agent 是执行体，不是建模对象 + │ + codestable/ ← 所有产物持久化在文件系统 +``` + +--- + +## 模块 2：深度解析 (Deep Analysis) + +### 2.1 哲学内核：为什么"人在环"不是弱点而是设计选择 + +CodeStable 最受争议的点，也是它与主流框架最根本的分歧：**它认为程序员必须是"在环对象"**。 + +这个立场需要放在 2026 年的大背景下来理解。2026 年 2 月，Hashicorp 联合创始人 Mitchell Hashimoto 提出了 **Harness Engineering（驾驭工程）** 概念，核心哲学是"人类掌舵，Agent 执行"（Human Steer, Agent Execute）。很快，OpenAI、Anthropic、LangChain 等主流 AI 工具都采纳了这一范式。 + +CodeStable 可以理解为 Harness Engineering 在"编码工作流"这个细分领域的具体实现。它不是反对自动化——它反对的是**不留下痕迹的自动化**。 + +当你让 AI 自主完成一个 feature，对话结束后，你得到的是代码。但你失去了： +- 为什么要这么设计？ +- 当时有哪几种备选方案？ +- 这个设计依赖了哪些约束？ + +三个月后，另一个 developer（或三个月后的你）面对这段代码时，这些信息全部丢失了。 + +CodeStable 的回答是：**每做一个决定，就在 `codestable/` 目录里写下来。** 不是给 AI 写的 prompt，是给人读的文档。 + +### 2.2 6 个实体：软件要素的建模 + +这是 CodeStable 区别于所有其他框架的核心设计： + +```mermaid +flowchart TD + CS["cs 根入口"] --> ONBOARD["cs-onboard 初始化"] + ONBOARD --> REQ["cs-req: 需求实体"] + ONBOARD --> ARCH["cs-arch: 架构实体"] + + REQ --> ROADMAP["cs-roadmap: 路线图实体"] + ARCH --> ROADMAP + + ROADMAP --> FEAT["cs-feat: 特性流程"] + ROADMAP --> ISSUE["cs-issue: 问题流程"] + ROADMAP --> REFACTOR["cs-refactor: 重构流程"] + + FEAT --> FEAT_D["cs-feat-design"] + FEAT_D --> FEAT_I["cs-feat-impl"] + FEAT_I --> FEAT_A["cs-feat-accept"] + + ISSUE --> ISSUE_R["cs-issue-report"] + ISSUE_R --> ISSUE_A["cs-issue-analyze"] + ISSUE_A --> ISSUE_F["cs-issue-fix"] + + FEAT_A --> COMPOUND["compound: 知识沉淀"] + ISSUE_F --> COMPOUND + REFACTOR --> COMPOUND + + COMPOUND --> LEARN["cs-learn: 经验"] + COMPOUND --> TRICK["cs-trick: 模式"] + COMPOUND --> DECIDE["cs-decide: 决策"] + COMPOUND --> EXPLORE["cs-explore: 探索"] + + LEARN -. "下次被检索" .-> ARCH + TRICK -. "下次被检索" .-> FEAT_D + DECIDE -. "下次被检索" .-> ISSUE_A + EXPLORE -. "下次被检索" .-> ROADMAP +``` + +**实体 1：需求 (Requirement)** — 代码烂掉的最终逃生通道。需求文档保留了"为什么要有这个能力"的原始上下文。如果某个 feature 的实现彻底腐化了，你可以拿着需求文档让 AI 重新生成代码。 + +**实体 2：架构 (Architecture)** — "系统的编排层长什么样"。刻意强调**给人读的**，不是给 AI 自嗨的。这回应了作者对 OpenSpec 的批评——"生成的 Spec 抽象到人类没法读"。 + +**实体 3：路线图 (Roadmap)** — 大需求的拆解层。作者注意到一个关键问题："我想要一个权限校验系统"直接塞给 AI 是接不住的。必须先拆成模块 → 子 feature → 分配执行顺序。这是人在环中起核心作用的一层。 + +**实体 4：特性 (Feature)** — 实际落地的执行过程。design → impl → accept 三步闭环，design 是后续所有步骤的**唯一输入**。这种设计避免了 AI 在实现过程中"自己脑补"需求。 + +**实体 5：问题 (Issue)** — Bug 单，report → analyze → fix 三步走。关键创新是**analyze 和 fix 分离**——AI 常常急于修复而不理解根因，强制分开让每次修复都有理论依据。 + +**实体 6：知识 (Compound)** — CodeStable 最核心的差异优势。四种知识类型覆盖了软件工程中所有"值得记录"的时刻：经验 (learning)、模式 (trick)、决策 (decision)、探索 (explore)。这些知识会在下一次 `cs-arch`、`cs-feat-design`、`cs-issue-analyze` 时被自动检索。 + +### 2.3 分层架构：不是流水线，是"分层 + 事件驱动" + +CodeStable 的工作流不是一条线性流水线。它被组织成**5 层**： + +| 层 | 内容 | 触发时机 | +|----|------|---------| +| **阶段 0** | cs-onboard 初始化 `codestable/` 骨架 | 新项目接入时（一次） | +| **第 1 层** | cs-req / cs-arch 长效档案 | 需求和架构变更时（反复刷新） | +| **第 2 层** | cs-roadmap 规划层 | 大需求拆解时（按需进入） | +| **讨论入口** | cs-brainstorm 分诊 | 想法模糊时（可选） | +| **第 3 层** | cs-feat-* / cs-issue-* / cs-refactor-* | 事件驱动（来什么走什么） | +| **横切层** | cs-learn / cs-trick / cs-decide / cs-explore | 任何时候觉得"值得记下来" | + +**关键设计洞察**：第 1 层和第 2 层刻意分开。"系统现在长什么样"和"接下来打算怎么走"是两个不同的问题。大部分 Spec 驱动框架把两者混在一个 Spec 文件里，导致"现状"和"规划"边界模糊。CodeStable 的解决方式是用不同的目录和不同的技能来管理。 + +### 2.4 运行时结构：`codestable/` 目录设计 + +``` +你的项目/ +├── codestable/ +│ ├── requirements/ # 需求（"为什么要有这个能力"） +│ ├── architecture/ # 架构（"用什么结构实现"） +│ ├── roadmap/ # 路线图（"接下来怎么走"） +│ ├── features/YYYY-MM-DD-{slug}/ # 特性执行 +│ │ ├── {slug}-design.md # 方案（唯一输入） +│ │ ├── {slug}-checklist.yaml # 清单（impl 跑、accept 回写） +│ │ └── {slug}-acceptance.md # 验收报告 +│ ├── issues/YYYY-MM-DD-{slug}/ # 问题修复 +│ ├── refactors/YYYY-MM-DD-{slug}/ # 重构（beta） +│ ├── compound/ # 知识沉淀 +│ │ └── YYYY-MM-DD-{doc_type}-{slug}.md +│ ├── tools/ # 共享脚本 +│ └── reference/ # 共享参考文档 +└── AGENTS.md +``` + +**三条设计原则**： +1. **所有产物聚在一个目录下** → "上次那个 feature 怎么搞的，三秒找到" +2. **日期前缀** → 按时间排序天然就是开发历史 +3. **compound 用 type 字段区分而非分目录** → 方便跨类型搜索 + +### 2.5 硬约束：Skill 隔离与跨 Skill 共享 + +CodeStable 有一个重要的工程约束：**每个 skill 运行时只能看到自己包内的文件**。这意味着 SKILL.md A 不能直接引用 B 的 reference 文件。 + +解决方案：`cs-onboard` 在初始化时从技能包**复制**共享文档到项目的 `codestable/reference/`，其他 skill 通过项目相对路径读取。 + +这本质上是一个**依赖注入**模式——技能是通用逻辑，`codestable/` 是注入的运行时上下文。和我们在 mattpocock/skills 中看到的 `setup-matt-pocock-skills` 设计如出一辙。 + +--- + +## 模块 3：深度裂变 (Deep Fission) + +### 🔍 "编排软件要素"是真的范式创新，还是旧酒新瓶？ + +这是对 CodeStable 最尖锐的批判性审视。 + +**正方：确实在范式层面做了翻转** + +所有主流 AI 编码框架（截至 2026 年 5 月）都在"Agent 编排"这个范式下工作。它们回答的问题是："Agent 之间怎么分工？怎么协调？怎么传递上下文？"CodeStable 问的是另一个问题："软件的需求、约束、决策怎么被记下来、被检索、被复用？" + +这个翻转在实践层面有一个直接后果：**知识沉淀从"副作用"变成了"一等公民"**。在 SuperPowers 中，你跑完一个 TDD 循环，你得到的是代码和测试。在 CodeStable 中，你跑完一个 feature，你得到的是代码 + design 文档 + acceptance 报告 + （可选的）compound 知识条目。后者在"三个月后还能被理解"这个维度上有结构性优势。 + +**反方：有四个没有解决的问题** + +1. **知识检索依赖 AI 的上下文窗口**。compound/ 目录里的文件再多，最终还是要靠 AI "读" 来检索。如果 compound 积累了 200 个文件，AI 能一次读完吗？CodeStable 目前依赖 AI 在启动时选择性读取相关文件，没有真正的索引或向量检索。 + +2. **没有强制执行机制**。SuperPowers 的 TDD 是铁律——你跳过 RED 阶段，它直接中断你。CodeStable 的 `cs-feat-accept` 是验收，但验收的执行深度取决于你。如果人把关不严，整个质量门形同虚设。 + +3. **cs-brainstorm 的"分诊"能力受限于模型理解能力**。让 AI 判断一个模糊想法"该走 design 还是进 roadmap 还是直接 feature"——这个判断本身就需要很高的理解力。模型理解错了，整个流程从一开始就偏了。 + +4. **对比并非完全公平**。OpenSpec 的 Spec 文件设计目标就是**机器和人双读**，作者批评它"抽象到人类没法读"，但很多 OpenSpec 用户的实际体验并非如此。这可能更多是使用方式和配置问题，而非框架本身的设计缺陷。 + +🔍 **搜索内化**：根据 V2EX 和 LINUX DO 社区讨论，CodeStable 的实际用户反馈总体积极——"正确性对我来说够了，按照流程生成完，手动审查，不复杂的需求基本一次性搞定"——但用户也指出了"上下文一长就会忘"的知识检索问题。CodeStable 作者在 README Roadmap 中也坦承项目处于早期阶段，多个模块（如 `cs-refactor`）仍在 beta。 + +### 🔍 一个被忽略的关键信号：CodeStable 承认自己会"过时" + +在 README 的 Roadmap 部分，有这样一句话： + +> "CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。" + +这让 CodeStable 区别于绝大多数 AI 框架——它不是试图建立一个永恒的体系，而是**承认自己是一个过渡性工具**。当未来的 AI 模型强到不需要手工组织软件要素时，CodeStable 的使命就完成了。 + +这种"自我消解的诚实"在 AI 工具领域极为罕见。大多数框架在讲"未来五年"的故事。CodeStable 在讲"在 AI 还不够好的当下，这样工作最舒服"。 + +--- + +## 模块 4：实战指南 (Actionable Guide) + +### 4.1 如何开始 + +```bash +# 安装 +npx skills add https://github.com/liuzhengdongfortest/CodeStable + +# 初始化项目 +/cs-onboard + +# 日常使用——不知道用哪个就喊根入口 +/cs +``` + +### 4.2 典型工作流 + +**场景 A：新增功能** +``` +/cs-feat # 进入特性流程 +/cs-feat-design # 写 design 文档（后续的唯一输入） +/cs-feat-impl # 按 design 推进写代码 +/cs-feat-accept # 对照 design 验收 +``` + +**场景 B：修 Bug** +``` +/cs-issue # 进入问题流程 +/cs-issue-report # 落成可复现的 report +/cs-issue-analyze # 找根因、评估风险 +/cs-issue-fix # 定点修复 + 验证 +``` + +**场景 C：快速小改动** +``` +/cs-feat-ff # 超轻量通道，跳过 design/accept +``` + +**场景 D：沉淀知识** +``` +/cs-learn # 踩坑经验 +/cs-trick # 可复用模式 +/cs-decide # 技术决策 +``` + +### 4.3 避坑指南 + +| 🔴 反模式 | ✅ 正确做法 | +|-----------|-----------| +| 跳过 cs-onboard，手动创建 codestable/ 目录 | 必须用 cs-onboard 初始化，确保 reference/ 被正确复制 | +| cs-feat-impl 中不看 design 自己脑补 | design 是唯一输入，偏离 design 必须回退更新 design | +| 所有改动都走 cs-feat（太重） | 小改动用 cs-feat-ff，大功能走完整流程 | +| compound 文件乱命名 | 严格遵循 `YYYY-MM-DD-{type}-{slug}.md` 格式，好搜 | +| 不写 acceptance 报告 | cs-feat-accept 的验收报告是"三个月后能理解"的关键 | + +### 4.4 CodeStable 与你现有工作流的融合点 + +如果你已经有 `/dev-flow`（openspec + grill-with-docs + zoom-out + apply + diagnose），CodeStable 可以和它互补使用： + +| dev-flow 阶段 | CodeStable 替代/增强 | +|--------------|---------------------| +| Phase 0 初始 PRD | `cs-req` 沉淀为需求文档（更持久） | +| Phase 1.5 结构化 PRD | `cs-feat-design` 作为 design 文档 | +| Phase 2 grill-with-docs | `cs-brainstorm` 作为讨论入口 | +| Phase 2.5 zoom-out | `cs-arch` 单独维护架构文档 | +| Phase 3 执行 | `cs-feat-impl` + `cs-feat-accept` | +| Phase 4 收尾 | `cs-learn` / `cs-decide` 沉淀知识（比 CONTEXT.md 更结构化） | + +**关键差异**：dev-flow 的产出散落在 `docs/` 和 `CONTEXT.md` 中。CodeStable 的产出全部集中在 `codestable/` 下，用统一的命名约定管理。如果你的项目预计跨年维护，这种集中管理会越来越有价值。 + +### 4.5 ROI 分析 + +| 投入 | 产出 | +|------|------| +| cs-onboard 初始化：2 分钟 | 建好所有目录骨架和共享 reference | +| 跑完一个 feature 流程：比原来 OpenSpec 多 5-10 分钟 | 留下 design + acceptance + 可选的 compound，三个月后可回溯 | +| 学习 22 个技能：30-45 分钟 | 覆盖需求→架构→特性→问题→重构→知识的完整链路 | + +--- + +## 模块 5：温故知新 (Consolidation) + +### 常见陷阱 (FAQ) + +
+Q: CodeStable 和 dev-flow 谁更好？ +不是替代关系。dev-flow 是流程编排元技能（"按什么步骤走"），CodeStable 是一套完整的软件生命周期建模体系（"软件要素怎么组织"）。可以组合使用：dev-flow 的 grill-with-docs 补充 CodeStable 缺少的"术语对齐"阶段；CodeStable 的 compound 补充 dev-flow 缺少的"结构化知识沉淀"。 +
+ +
+Q: CodeStable 适合一个人用吗？ +非常适合。CodeStable 的设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作、没有审批流。它帮助单人开发者维持跨时间的一致性。如果是一个人维护的长期项目，CodeStable 是目前最合适的框架。 +
+ +
+Q: CodeStable 和 SuperPowers 能一起用吗？ +理论上可以，但不推荐。两者的哲学是对立的——SuperPowers 希望人少介入，CodeStable 要求人在环。同时用会导致认知冲突："这一步到底是让 AI 自己决定，还是我来把关？"建议根据项目类型选一个主线。 +
+ +
+Q: codestable/ 目录会变得很臃肿吗？ +会。这是有意为之。作者认为"臃肿"的文档目录好过"干净"的失忆。每个 feature 都留下完整的 design + acceptance，长期积累确实会很多文件。但日期前缀命名使按时间浏览很自然，且 compound 通过 type 字段做聚合。 +
+ +
+Q: 轻量通道 cs-feat-ff 什么时候用？ +当你有一个非常明确的小改动——比如"把这个按钮的颜色改成蓝色"、"加一个表单字段"——不需要写 design 文档和完整的 acceptance 报告。但作者的建议是："如果不确定该不该走 ff，就走完整流程"。 +
+ +
+Q: 如果我不想用全部 22 个技能怎么办？ +CodeStable 的技能是松耦合的。你可以只用 cs-req + cs-feat-* 做特性开发，跳过 cs-roadmap 和 cs-refactor。最精简的子集：cs-onboard + cs-req + cs-feat + cs-issue。 +
+ +
+Q: CodeStable 的 knowledge 检索能力有多强？ +目前是"文件命名约定 + AI 选择性读取"模式，而非向量语义检索。当 compound/ 积累到 50+ 个文件后，AI 可能无法一次读完所有文件，需要在 prompt 中引导 AI 只读相关的。作者在 Roadmap 中表示关注这个问题。 +
+ +
+Q: 和 mattpocock/skills 的关系？ +同样是 Agent Skills 的封装形式，但建模哲学完全不同。mattpocock 的技能是"小工具"——每个技能解决一个特定问题（grill、diagnose、tdd）。CodeStable 的技能是"体系"——每个技能是软件生命周期中的一个步骤。前者灵活可组合，后者完整有体系。 +
+ +### 自测题 + +1. CodeStable 的 6 个软件实体是哪 6 个？每个的核心用途是什么？ +2. "编排 Agent"和"编排软件要素"的根本区别是什么？这种区别在工程实践上会产生什么不同的后果？ +3. CodeStable 的 3 个核心流程分别是什么？每个流程的技能链是什么？ +4. `cs-feat-design` 为什么被设计为"后续所有步骤的唯一输入"？这种设计避免了什么问题？ +5. `compound/` 目录下的 4 种知识类型分别是什么？它们会在什么时机被 AI 重新检索？ +6. CodeStable 为什么要求每个 skill 运行时只能看到自己包内的文件？这个硬约束解决了什么问题？ +7. CodeStable 作者所说的"复利工程"（Compound Engineering）具体指什么？ +8. 如果你要将 CodeStable 集成到你现有的 dev-flow 中，哪些 Phase 可以保留、哪些可以用 CodeStable 替换？ + +### 参考资源 + +- GitHub 仓库：https://github.com/liuzhengdongfortest/CodeStable +- 作者的项目 MA：https://github.com/liuzhengdongfortest/MA +- Harness Engineering 概念起源（Mitchell Hashimoto, 2026.02） +- V2EX 讨论帖：https://global.v2ex.co/t/1208525 + +--- + +*© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过* diff --git a/openspec/changes/add-year-filter/design.md b/openspec/changes/add-year-filter/design.md new file mode 100644 index 0000000..9207323 --- /dev/null +++ b/openspec/changes/add-year-filter/design.md @@ -0,0 +1,31 @@ +## Context + +当前知识索引页面是单文件静态 HTML，由 `scripts/update-knowledge-index.sh` 生成。数据源 `ENTRIES` 中每个条目都有 `date` 字段，格式为 `YYYYMMDD`，页面渲染时已经用该字段展示 `YYYY-MM-DD`。 + +## Design + +新增年份筛选采用纯前端派生数据： + +1. 从 `ENTRIES` 中读取有效 `date`。 +2. 取前四位作为 year。 +3. 去重后按年份倒序生成 ` + + +
+ + + +
+ +
没有找到匹配的条目
+ +
+ +
+ +
+由 scripts/update-knowledge-index.sh 生成 · +
+ + + + + + +HTMLEOF + +# ---- Phase 4: Done ---- +echo "[4/4] Done!" +echo " Output: $OUTPUT" +echo " Entries: $count" +echo " Open with: start knowledge-index.html" + + + diff --git a/skill-workbench/docs/explore-essence-follow/latest-design.md b/skill-workbench/docs/explore-essence-follow/latest-design.md new file mode 100644 index 0000000..e04a55a --- /dev/null +++ b/skill-workbench/docs/explore-essence-follow/latest-design.md @@ -0,0 +1,270 @@ +# Explore / Essence / Follow 最新设计总结 + +**版本基线**：v0.5.0 +**对应 skill 本体**：`skill-workbench/generated-skills/skills/` +**历史来源**： + +- `skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md` +- `skill-workbench/history/docs/superpowers/specs/` +- `skill-workbench/history/docs/superpowers/changelog/` + +## 一句话定位 + +`explore`、`essence`、`follow` 是一组学习型 skill family： + +- `explore` 负责项目级理解。 +- `essence` 负责深挖 1-2 个最值得迁移的核心设计。 +- `follow` 负责基于已有报告做交互式跟学。 + +三者不是“深浅不同的同一个技能”，而是学习链路中的三个不同角色。 + +## 设计背景 + +早期 superpowers 设计试图覆盖完整学习过程，但在实践中出现了几个问题： + +1. 阶段过多，`explore` 同时承担项目理解、深度分析、教学输出，边界不清。 +2. `/essence` 曾被误设计成 `/explore` 的轻量版，导致无法稳定聚焦“值得偷走的设计”。 +3. `/follow` 曾倾向重新扫描项目，削弱了它“基于已有报告教学”的定位。 +4. HTML、Deep Fission、Verify 等输出阶段让 skill 变重，增加上下文和执行成本。 +5. 历史 docs 中存在过时 proposal、plan 和已删除技能引用，需要收敛为当前真实实现。 + +v0.5.0 的核心改造是：**拆清职责，减少阶段，只保留能稳定触发、稳定产出的学习动作。** + +## 三技能职责边界 + +| Skill | 核心问题 | 输入 | 输出 | 不做什么 | +| --- | --- | --- | --- | --- | +| `explore` | 这个项目是什么，为什么值得学，从哪里开始？ | 新项目、代码仓库、文档仓库、skill 仓库 | 项目学习报告、结构图、2-3 个核心设计概览 | 不做深度模式提取，不做互动教学 | +| `essence` | 这个项目最值得偷走的设计是什么？ | 明确设计目标，或需要自动找 standout design | 设计模式卡、证据链、迁移示例 | 不做全项目概览，不做普通代码讲解 | +| `follow` | 如何基于已有报告一步步学会？ | 已有 `/explore` 或 `/essence` 报告 | Runnable 或 Reader 跟学会话 | 不重新扫描项目，不替用户执行代码 | + +## 推荐学习链路 + +```text +第一次接触项目 + ↓ +/explore + 产出项目定位、结构、主流程、核心设计候选 + ↓ +/essence + 选择一个核心设计做深挖，提炼可迁移模式 + ↓ +/follow + 基于 explore/essence 报告做交互式学习 +``` + +也可以单独使用： + +- 只想快速建立全局认知：只用 `explore`。 +- 已经知道要研究哪个设计：直接用 `essence` 的 User-directed 模式。 +- 已经有报告，想按教程学：直接用 `follow`。 + +## Explore 最新设计 + +### 定位 + +`explore` 是项目地图绘制器。它回答： + +- 这个项目是什么？ +- 为什么值得研究？ +- 顶层结构如何组织？ +- 学习入口在哪里？ +- 有哪 2-3 个核心设计值得后续深挖？ + +### 当前阶段 + +v0.5.0 将原来的 5 Phase 收敛为 4 Phase： + +1. **Positioning & Structure** + - 合并早期 Positioning 和 Structure。 + - 输出项目定位、学习价值、顶层结构、入口区域。 +2. **Flow** + - 仅代码仓库执行。 + - 追踪主运行流或请求流，聚焦 golden path。 +3. **Start Path** + - 仅代码仓库且可运行/可观察时执行。 + - 给出最小启动路径、第一条命令或第一处观察点。 +4. **Core Designs** + - 总结 2-3 个核心设计或核心想法。 + - 保持概览深度，为 `essence` 提供候选对象。 + +### 类型分流 + +`explore` 必须先识别项目类型： + +- **Code repository**：执行完整 4 Phase。 +- **Skill / docs / knowledge repository**：跳过 Flow 和 Start Path，改用结构图、概念图或 workflow 图。 +- **Template / scaffold repository**：Flow 和 Start Path 可以保持轻量。 + +### 关键约束 + +- 不做 `/essence` 级别深挖。 +- 不做 `/follow` 式互动教学。 +- 不保留 Verify、Deep Fission、HTML Output 等已退休阶段。 +- 最终必须至少包含一个图：代码仓库用架构/流程图，非代码仓库用结构/想法/workflow 图。 + +## Essence 最新设计 + +### 定位 + +`essence` 是“宝石检查器”。它不是 `/explore` 的轻量版，而是专门回答： + +> 这个项目里哪 1-2 个设计最值得迁移到我自己的工程里？ + +### 模式 + +| Mode | 触发场景 | 行为 | +| --- | --- | --- | +| User-directed | 用户已有目标，或来自 `/explore` 的核心设计候选 | 直接深挖用户指定设计 | +| Auto-detect | 独立启动，用户希望 AI 自动找亮点 | 扫 README、docs、结构和信号，提出 1-2 个候选 | +| Lens-guided | 用户指定 mechanical / intentional / evolution 视角 | 按透镜选择证据来源和输出框架 | + +### 透镜 + +- **Mechanical**：它如何工作？读代码、接口、调用链。 +- **Intentional**：为什么这样设计？读设计文档、RFC、PR、权衡。 +- **Evolution**：它如何演化到这里？读 changelog、git 历史、迁移记录。 + +### 当前阶段 + +1. **Locate** + - 找到 1-2 个候选设计方向。 + - 自动模式要求 standout design 至少满足 2 个信号。 +2. **Deep Dive** + - 最多读 10 个核心文件。 + - 追踪调用链或证据链，避免扩散成全项目分析。 +3. **Extract Pattern** + - 提炼问题、模式、替代方案、权衡和证据。 +4. **Migrate** + - 给出可迁移方式和最小示例。 + - 示例必须足够小，避免复制生产代码。 +5. **Self-review** + - 检查是否有证据、是否解释了权衡、是否能迁移。 + +### 关键约束 + +- “代码干净”不是 essence 信号。 +- 如果没有 standout design，应明确建议改用 `explore`。 +- 如果设计边界超过 10 个文件且无法收敛，应改用 `explore`。 +- HTML Card 只是显式请求时的可选输出，不是默认阶段。 + +## Follow 最新设计 + +### 定位 + +`follow` 是跟学教练。它不做新分析，只基于已有 `/explore` 或 `/essence` 报告，带用户一步步学习。 + +### 前置条件 + +必须存在以下之一： + +- `/explore` 报告 +- `/essence` 报告 + +如果没有，必须拒绝并引导用户先运行 `explore` 或 `essence`。 + +### 模式 + +| Mode | 来源 | 行为 | +| --- | --- | --- | +| Runnable | `/explore` 报告确认是可运行代码仓库 | 从环境、启动、观察和安全修改开始 | +| Reader | 非代码仓库，或来自 `/essence`，或用户专注设计学习 | 围绕核心设计做分层阅读和推理练习 | + +### 当前流程 + +**Runnable**： + +1. 确认环境和依赖。 +2. 让用户运行项目。 +3. 让用户做一个安全小改动。 +4. 一起走主流程。 +5. 给一个小练习。 +6. 回顾学习结果。 + +**Reader**： + +1. 围绕设计或架构想法设定学习目标。 +2. 按“问题 → 方法 → 实现 → 权衡”讲解。 +3. 通过问题检查理解。 +4. 用图或结构总结连接文件和设计。 +5. 给一个迁移/推理练习。 +6. 回顾学习结果。 + +### 关键约束 + +- 不重新扫描项目。 +- 不执行命令或替用户写代码。 +- 不新增第三种模式。 +- 不只说“去读这个文件”，必须说明这个文件体现什么设计、为什么重要、看什么。 + +## v0.5.0 最重要的收敛 + +### 1. Explore 从 5 Phase 收敛到 4 Phase + +早期 Positioning 和 Structure 拆开导致报告啰嗦。v0.5.0 合并为 `Positioning & Structure`，让 `explore` 更像项目地图，而不是流水账。 + +### 2. Essence 补齐上下文感知 + +`essence` 会先判断是否已有 `/explore` 结果： + +- 有结果：默认 User-directed，让用户从候选设计中选择。 +- 无结果：默认 Auto-detect，自行寻找 standout design。 + +这避免了 `essence` 在已有上下文时重复扫描。 + +### 3. Follow 不再重扫 + +`follow` 的核心价值是“基于报告教学”。如果它重新扫描项目，就会变成另一个 explore。v0.5.0 明确它必须读取前置报告，按报告决定 Runnable 或 Reader。 + +### 4. Reader 模式从文件级提升到设计级 + +早期 Reader 容易变成“带你读一个文件”。v0.5.0 改成围绕设计概念学习：问题、方法、实现、权衡。 + +### 5. 删除过期阶段和死引用 + +已退休内容包括： + +- Deep Fission +- Verify 阶段 +- 默认 HTML Output +- 旧 `/map`、`/fission` 等已不存在技能引用 + +## 当前产物边界 + +```text +skill-workbench/ +├── generated-skills/ +│ └── skills/ +│ ├── explore/ +│ ├── essence/ +│ └── follow/ +├── docs/ +│ └── explore-essence-follow/ +│ └── latest-design.md +└── history/ + ├── changelog/ + └── docs/superpowers/ +``` + +- `generated-skills/skills/` 只放可安装 skill 本体。 +- `docs/explore-essence-follow/latest-design.md` 保存最新设计总结。 +- `history/` 保留旧设计、changelog、handoff 和过时 specs，作为考古来源。 + +## 何时修改哪一层 + +| 变更类型 | 修改位置 | +| --- | --- | +| skill 行为变更 | `skill-workbench/generated-skills/skills/{skill}/SKILL.md` | +| 最新设计说明变更 | `skill-workbench/docs/explore-essence-follow/latest-design.md` | +| 历史记录 | `skill-workbench/history/`，不要覆盖 | +| 验证材料 | `skill-workbench/validation/` | + +## 当前结论 + +这组三技能已经形成清晰分工： + +- `explore` 是入口：建立项目级地图。 +- `essence` 是深挖：提炼可迁移设计。 +- `follow` 是教学：基于报告引导用户学会。 + +后续改进应避免把三者重新合并。最重要的维护原则是：**保持边界比增加功能更重要。** diff --git a/skill-workbench/docs/sm-flow/workflow.md b/skill-workbench/docs/sm-flow/workflow.md new file mode 100644 index 0000000..5e90818 --- /dev/null +++ b/skill-workbench/docs/sm-flow/workflow.md @@ -0,0 +1,383 @@ +# 增强版工作流总结 + +## 旧工作流 vs 新工作流 + +``` +旧： 新： +Phase 1 手动整理PRD Phase 0 手动初始PRD（入口，保留人的判断） +Phase 2 openspec:explore Phase 1 openspec:propose → research +Phase 3 grill-me Phase 1.5 to-prd → 结构化PRD（替代初始PRD） +Phase 4 openspec:apply Phase 2 grill-with-docs → CONTEXT.md + ADR + Phase 2.5 zoom-out → 架构审计 + Phase 3 openspec:apply → 执行 + diagnose → bug排查 + tdd → 质量闭环 +横切： 横切： + 无 git-guardrails → 安全锁 +``` + +关键变化：**手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"**——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。 + +## 旧工作流的三个关键缺口 + +1. **需求澄清后缺少可行性验证** + - 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现 + - 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行" + +2. **openspec 产出不能沉淀到长期记忆** + - 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢 + - 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文 + +3. **apply 完成后缺少验证闭环** + - 旧：apply → 完成。功能对不对取决于人肉测试 + - 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor） + +## 新增技能的投入产出 + +| 技能 | 学多久 | 一次省多少 | 什么时候用 | +|------|--------|-----------|-----------| +| to-prd | 0 分钟（自动综合） | 10-15 分钟 | openspec research 结束后 | +| grill-with-docs | 替换已有 grill-me | 0 额外时间 + 产出文档 | 需求澄清阶段 | +| zoom-out | 10 秒（一句话） | 避免方向性返工 | grill 完成后、apply 前 | +| diagnose | 5 分钟了解流程 | 每次 bug 省 20-30 分钟 | apply 中遇到问题 | +| tdd | 5 分钟了解流程 | 减少回归 bug | apply 中写代码 | +| git-guardrails | 0 分钟（被动生效） | 防止灾难性操作 | 全程自动 | + +## 为什么这套组合优于单纯依赖 openspec + +openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题： + +- **领域知识沉淀**：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐 +- **质量验证**：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环 +- **流程安全**：openspec 不管 AI 误操作 → git-guardrails 补齐安全层 + +一句话：**openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。** + +## v2.0：devflow/ 产物聚合层 + +### 问题 + +v1.0 一次完整流程的产物散落在 **5 个位置**： + +``` +CONTEXT.md ← Phase 2 (根目录) +docs/adr/ ← Phase 2 (docs/) +docs/agents/ ← Phase 1.5 (docs/) +openspec/changes/ ← Phase 1+3 (openspec/) +knowledge/entries/ ← /knowledge-absorber +``` + +三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按**工具来源**组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按**项目本身**组织。 + +### 借鉴 CodeStable 的单一聚合根设计 + +CodeStable 的核心设计决策：所有产物集中在 `codestable/` 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。 + +dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个**人类可读的档案层**： + +``` +devflow/ ← 单一入口 +├── projects/YYYY-MM-DD-{slug}/ ← 一个 PRD→实现 闭环 +│ ├── {slug}-prd.md # Phase 0+1.5 需求文档 +│ ├── {slug}-research.md # Phase 1 技术方案（从 openspec 提取） +│ ├── {slug}-design.md # Phase 1+2.5 设计 + 架构审计 +│ ├── {slug}-tasks.md # Phase 1 任务清单（从 openspec 提取） +│ ├── {slug}-acceptance.md # Phase 3+4 验收报告 +│ └── adr/ # Phase 2 架构决策 +├── glossary/ +│ └── CONTEXT.md # 跨项目领域词汇表 +├── compound/ # 跨项目知识沉淀 +│ └── YYYY-MM-DD-{type}-{slug}.md # type ∈ {learning, trick, decision, explore} +└── reference/ # 共享模板/规范 +``` + +### 两层架构 + +| | openspec/changes/ | devflow/projects/ | +|------|-----------|-------------------| +| 角色 | 工具工作区（WAL） | 人类档案层（Tables） | +| 谁读 | 机器 | 人 | +| 生命周期 | 活跃变更期 → Archive 后清空 | 永久保留 | +| 组织方式 | 按变更名 | 按日期 + 项目 | + +**关键**：openspec archive 后 `openspec/changes/` 清空，但 `devflow/projects/` 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。 + +### 各 Phase 产物路径变化 + +| Phase | v1.0 | v2.0 | +|-------|------|------| +| 1.5 PRD | `docs/agents/-prd.md` | `devflow/projects/{date}-{slug}/{slug}-prd.md` | +| 2 CONTEXT | 根目录 `CONTEXT.md` | `devflow/glossary/CONTEXT.md` | +| 2 ADR | `docs/adr/` | `devflow/projects/{slug}/adr/` | +| 2.5 架构审计 | 对话中，丢失 | `devflow/projects/{slug}/{slug}-design.md` | +| 4 验收 | `docs/agents/lessons/` | `devflow/projects/{slug}/{slug}-acceptance.md` | +| 4 经验沉淀 | 无 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` | +| 4 从 openspec 提取 | 无 | 提炼到 `{slug}-research.md` + `{slug}-tasks.md` | + +## 一键启动 + +已固化为 skill：**`/dev-flow`** + +``` +/dev-flow # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程 +/dev-flow --prd docs/my-idea.md # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1 +/dev-flow --from phase2 # 已有 research，从 grill 开始 +/dev-flow --from apply # 已有 PRD + 文档，直接执行 +/dev-flow --quick # 小需求，跳 PRD 精化 + zoom-out +``` + +Skill 位置：`.claude/skills/dev-flow/SKILL.md` + +## Skill 评估结论（2026-05-19） + +详细评估报告见：`devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md`。 + +### 总体判断 + +`dev-flow` 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。 + +最有价值的设计是 `devflow/` 产物聚合层： + +- `openspec/changes/` 负责机器可执行的变更工作区。 +- `devflow/projects/` 负责人类可回溯的项目档案。 +- `devflow/glossary/CONTEXT.md` 负责跨项目领域词汇。 +- `devflow/compound/` 负责沉淀可复用工程知识。 + +评估中发现的核心问题是：早期 `SKILL.md` 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。 + +### 已确认的亮点 + +1. **产物聚合层设计清晰** + - `devflow/projects/YYYY-MM-DD-{slug}/` 解决了 openspec archive 后上下文难以回溯的问题。 + - 工具工作区和人类档案层分离，职责边界明确。 + +2. **阶段顺序合理** + - Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。 + +3. **Phase 4 很有价值** + - 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。 + - 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。 + +4. **文档化追问方向正确** + - Phase 2 要求一次只问一个问题，并即时更新 `CONTEXT.md` / ADR。 + - 这符合“边澄清边沉淀”的工作方式。 + +5. **质量闭环意识强** + - Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。 + - TDD 被设计为可选增强，避免对所有任务强制套用重流程。 + +### 主要改进点 + +| 问题 | 改进方向 | +| --- | --- | +| 触发描述不够完整 | 明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景 | +| Claude 工具耦合较强 | 保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback | +| 依赖安装状态写死 | 改为启动时检查 required / optional / fallback | +| 子 skill 调用方式不稳 | 优先调用子 skill；不可调用时读取对应 `SKILL.md`；不存在时执行最小协议 | +| 缺少初始化算法 | 明确 `devflow/` 目录骨架、slug 生成、重名处理和旧 `CONTEXT.md` 迁移规则 | +| 缺少模板 | 拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板 | +| quick 模式与约束冲突 | quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档 | +| Phase 退出条件不足 | 为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径 | + +### 产品化方向 + +评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”： + +- `SKILL.md` 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。 +- `references/` 承载长内容：Phase 契约、模板、归档规则、fallback 协议。 +- 每个 Phase 都要有明确的进入条件和退出条件。 +- quick 模式、fallback、归档确认、人类检查点必须写成硬规则。 +- `devflow/` 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。 + +### 后续演进：sm-flow 产品化 + +基于这次评估，`dev-flow` 的设计被重构为 `.agents/skills/sm-flow/`。这一步仍属于 **v2 产品化**：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。 + +``` +.agents/skills/sm-flow/ +├── SKILL.md # 短执行协议 +└── references/ + ├── phase-contracts.md # Phase 输入/动作/输出/退出条件 + ├── templates.md # PRD/ADR/验收等模板 + ├── archive-rules.md # 从 openspec 提取到 devflow 的规则 + └── fallbacks.md # 子 skill 不可用时的最小协议 +``` + +v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 `devflow/` 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。 + +## v3.0：OpenSpec-first / Devflow-assisted + +### 背景 + +v2 跑通后暴露出一个更深的问题：`devflow/` 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。 + +这会导致两套“执行依据”并存： + +``` +devflow/projects/{slug}/... # 人类档案层，也包含 PRD/design/tasks +openspec/changes/{change}/... # 工具工作区，也包含 proposal/design/specs/tasks +``` + +如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。 + +### v3 的核心判断 + +v3 不重新设计一套替代 openspec 的工作流，而是明确： + +> **devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。** + +职责分层变为： + +| 层 | 角色 | 负责回答 | +| --- | --- | --- | +| `devflow/` | 上下文真理源 / 长期记忆 | 为什么这样做？术语是什么？历史决策是什么？之前怎么验收？ | +| `openspec/changes/` | 执行真理源 / 当前变更规格 | 这次到底改什么？验收标准是什么？任务是否完成？ | +| code | 实现结果 | OpenSpec apply 后实际落地的代码 | + +### v2 vs v3 + +| 维度 | v2：devflow 聚合层 | v3：OpenSpec-first / Devflow-assisted | +| --- | --- | --- | +| 核心目标 | 防止 openspec archive 后上下文丢失 | 防止 devflow 与 openspec 成为并列执行源 | +| devflow 角色 | 人类可读档案层 | 上下文增强层 + 归档层 | +| openspec 角色 | 工具工作区 | 当前变更的唯一默认执行真理源 | +| Phase 1 | openspec propose 产出 research | 基于 devflow 上下文生成/修正 OpenSpec 产物 | +| Phase 2 | grill-with-docs 更新 glossary/ADR | human-in-the-loop 澄清后必须回写 OpenSpec | +| Phase 2.5 | zoom-out 产出架构审计 | 架构审计若影响实现，必须回写 OpenSpec design/tasks | +| Phase 3 | openspec apply + diagnose/tdd | 默认只能依赖 OpenSpec apply；devflow 只作参考上下文 | +| Phase 4 | 从 openspec 提炼到 devflow | 轻量回填 devflow 必要档案，避免重复 OpenSpec | + +### v3.1：Devflow 产物瘦身 + +v3 继续跑完整流程后，又暴露出一个实践问题：`devflow` 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。 + +因此 v3.1 明确：**devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。** + +默认必要产物收敛为： + +```text +devflow/projects/YYYY-MM-DD-{slug}/ +├── brief.md # 背景、目标、范围、非目标、关联 OpenSpec +├── evidence.md # 代码/文档证据、evidence-driven 结论和汇报状态 +├── decisions.md # user-interview 确认、关键取舍、OpenSpec 回写记录 +└── acceptance.md # 实现结果、验证、未验证项、archive 状态 +``` + +扩展产物只在有明确理由时创建： + +- `prd.md`：复杂需求、对外协作或用户明确要求。 +- `research.md`：真实调研、代码考古、竞品/API 对比或复杂方案比较。 +- `design.md`：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。 +- `tasks.md`：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。 +- `alignment.md` / `clarifications.md`：冲突或澄清问题很多时拆出；否则并入 `decisions.md`。 + +规模分档： + +| 分档 | 适用场景 | devflow 默认产物 | +| --- | --- | --- | +| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md` | +| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | +| `complex` | 高风险、跨模块、需求不清、多人协作 | standard + 按需 PRD/research/design/tasks/alignment | + +### v3 新增 Phase 0.5 + +v3 在 Phase 0 和 Phase 1 之间增加： + +``` +Phase 0.5 Devflow Context Harvest +``` + +读取： + +- `devflow/glossary/CONTEXT.md` +- 相关项目 PRD/design/tasks/acceptance +- 相关 ADR +- `devflow/compound/` 中的 learning、trick、decision、explore + +目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。 + + +### v3 中各 skill 的参与方式 + +这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”： + +| 阶段 | 主要 skill / 工具 | 作用 | 产物去向 | +| --- | --- | --- | --- | +| Phase 0 初始需求 / PRD / research | `sm-flow` | 收集原始需求、已有 PRD 或 research，判断启动模式 | 入口摘要、初步 slug | +| Phase 0.5 Devflow Context Harvest | `sm-flow` | 读取 `devflow/` 的 glossary、ADR、历史 PRD、acceptance、compound knowledge | 作为 Phase 1 的 OpenSpec 输入上下文 | +| Phase 1 OpenSpec propose | `openspec-propose` | 生成或修正 `proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md` | `openspec/changes//` | +| Phase 1.5 PRD / OpenSpec 对齐 | `to-prd` + `sm-flow` | 检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD | `brief.md` / 按需 `prd.md`；冲突回写 OpenSpec | +| Phase 2 Human-in-the-loop 澄清 | `grill-with-docs` | 追问术语、边界、验收；区分 `evidence-driven` 和 `user-interview` | `evidence.md` / `decisions.md`；影响实现的结论回写 OpenSpec | +| Phase 2.5 架构审计 | `zoom-out` | 拉高视角审查模块、数据流、耦合、架构风险 | 默认写入 decisions/evidence；复杂审计才拆 `design.md`；影响实现则回写 OpenSpec | +| Phase 3 OpenSpec apply | `openspec-apply-change` | 按 OpenSpec specs/tasks 执行实现 | 代码变更、OpenSpec task 状态 | +| Phase 3 bug/不确定行为 | `diagnose` | 复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归 | 根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance | +| Phase 3 高风险/复杂行为 | `tdd` | 按 OpenSpec specs 做纵向切片测试驱动 | 测试与实现代码 | +| Phase 4 回填 devflow | `sm-flow` + `openspec-archive-change` | 从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive | `devflow/projects/`、`devflow/compound/`；用户确认后 archive | + +说明：`grill-me` 在 v3 中不再作为主要入口，已被 `grill-with-docs` 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。 + +### v3 的执行规则 + +1. **OpenSpec 是执行真理源** + - Phase 3 默认必须依赖 `openspec/changes//proposal.md`、`design.md`、`specs/**/*.md`、`tasks.md`。 + - 不允许直接基于 `devflow/projects/...` 绕过 OpenSpec 写代码。 + +2. **Devflow 是上下文真理源** + - 术语、历史决策、项目背景、踩坑记录来自 `devflow/`。 + - 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。 + +3. **冲突先修 OpenSpec** + - 如果 devflow 和 OpenSpec 冲突，不能直接执行。 + - 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。 + +4. **evidence-driven 也必须汇报** + - 证据驱动不是“AI 自己确认完就继续”。 + - 代理必须汇报查了什么、得出什么结论、是否需要用户确认。 + +5. **user-interview 必须等待确认** + - 涉及范围、偏好、验收口径、风险接受度时，必须问用户。 + +6. **归档仍回到 devflow** + - OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。 + - Phase 4 询问是否 archive OpenSpec change，不默认执行。 + +7. **devflow 产物按需生成** + - 默认只生成 brief、evidence、decisions、acceptance。 + - PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。 + - 小需求走 `micro`，不能让文档成本超过实现成本。 + +### v3 流程图 + +``` +Phase 0 初始需求 / PRD / research + skill: sm-flow + ↓ +Phase 0.5 读取 devflow 上下文 + skill: sm-flow + ↓ +Phase 1 生成或修正 OpenSpec proposal/design/specs/tasks + skill: openspec-propose + ↓ +Phase 1.5 PRD / Devflow / OpenSpec 对齐检查 + skill: to-prd + sm-flow + ↓ +Phase 2 human-in-the-loop 澄清，并回写 OpenSpec + skill: grill-with-docs + ↓ +Phase 2.5 架构审计；影响实现则回写 OpenSpec + skill: zoom-out + ↓ +Phase 3 OpenSpec apply 执行 + skill: openspec-apply-change；按需 diagnose / tdd + ↓ +Phase 4 回填 devflow，并确认是否 archive + skill: sm-flow；用户确认后 openspec-archive-change +``` + +### v3 一句话定位 + +`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。 + + + + diff --git a/skill-workbench/generated-skills/skills/essence/SKILL.md b/skill-workbench/generated-skills/skills/essence/SKILL.md new file mode 100644 index 0000000..d444511 --- /dev/null +++ b/skill-workbench/generated-skills/skills/essence/SKILL.md @@ -0,0 +1,259 @@ +--- +name: essence +description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups. +metadata: + version: "0.5.0" +--- + +# Essence: Extract Core Design Patterns + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing. + +**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else. + +## Mode Selection + +First, check whether an `/explore` result exists: + +- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode. +- No `/explore` result → this is an independent launch, default to **Auto-detect**. + +Always confirm before proceeding: + +| Mode | When | Entry | +|---|---|---| +| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for | +| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design | +| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens | + +### Lens definitions + +| Lens | Core question | Guided behavior | +|---|---|---| +| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces | +| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs | +| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers | + +A lens shapes which sources to read and how to frame the output, but does not add separate phases. + +### Auto-detect signals + +A design is "essence" if it passes 2 or more of these signals: + +| Signal | Evidence | +|---|---| +| README highlights it prominently | "Built on a plugin architecture" as a headline feature | +| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author | +| Heavily discussed in Issues/PRs | Design decisions debated by community | +| Unique among similar projects | Competitors don't do it this way | +| Rich design comments in code | JSDoc/TSDoc explaining why, not what | +| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. | +| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic | +| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths | + +**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is. + +If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead." + +## Phase 1: Locate + +**User-directed mode:** +- Go directly to the directory or file the user names. +- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative. + +**Auto-detect mode:** +- Scan README, CLAUDE.md, and top-level docs for architecture claims. +- Identify 1-2 standout design directions. +- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?" +- If user doesn't choose, pick the strongest one and state why. + +**Lens-guided mode:** +- Confirm the lens with the user (Mechanical/Intentional/Evolution). +- Frame the search in terms of the lens. +- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern." + +**Output:** 1-2 design directions to analyze + lens confirmation. + +**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project. + +## Phase 2: Deep Dive + +Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides. + +**For each file:** +- What role does it play in this design? +- What interfaces does it expose? +- How does it connect to other parts of the system? + +**Trace the call chain:** +- Start from the entry point that uses this design. +- Follow the flow until you understand the full pattern. +- Stop when you hit boilerplate, config, or test files. + +**Output:** Core file list (≤10) + call chain + lens-specific annotations. + +**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead. + +## Phase 3: Extract Pattern + +Analyze the design at a higher level. Let the lens shape the analysis angle: +- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts +- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale) +- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events + +**Universal analysis dimensions** (all lenses): + +- **Problem:** What specific problem does this design solve? What was the pain before? +- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.) +- **Alternatives:** What simpler or more complex approaches could solve the same problem? +- **Tradeoffs:** Why did the author choose this? What does it give up? +- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.) + +**Output:** Design pattern card (lens-framed). + +**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report. + +## Phase 4: Migrate + +Make the learning actionable. Let the lens tailor the output: +- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs) +- **Intentional** → decision framework (checklist for evaluating tradeoffs) +- **Evolution** → migration path (step-by-step refactor plan) + +**Universal deliverables** (all lenses): + +- **Can you use this?** Is the design applicable to the user's own projects? If not, why? +- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example. +- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly? + +**Output:** Migration example + pitfall list (lens-tailored). + +**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code. + +## Phase 5: Self-review + +Check the report is honest: + +**All modes:** +- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited. +- [ ] The analysis is deep enough that you could explain it out loud. +- [ ] The migration example captures the core idea, not surface syntax. +- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere"). + +**Stall signals (any one → return to relevant phase):** +- Cannot name a file that proves the pattern → back to Phase 2 +- Cannot explain why it's better than alternatives → back to Phase 3 +- Migration example is over 20 lines → simplify, back to Phase 4 +- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase + +**Output:** Essence report with lens annotation. + +## Optional: HTML Card + +**Only when the user explicitly requests it.** + +Generate an HTML visualization card as a shareable deliverable. + +### HTML Card Structure (Glassmorphism 2.0 - Essence Variant) + +```html + + + + + {Project Name} - Essence Report + + + + + + + +
+
+

🎯 Design Analyzed

+

{one-line description}

+
+ +
+

🔷 Pattern ({lens})

+ +
+ +
+

🔗 Call Chain

+ 
{diagram}
+
+ +
+

📦 Migration Example

+ 
{code_example}
+

Pitfalls: {pitfalls}

+
+
+ + + + +``` + +### Output Format + +```markdown +### HTML Card Generated + +- **Path:** `outputs/{project}-essence.html` +- **Theme:** {modern/ink} +- **Accent Color:** Purple (essence = jewel) +``` + +**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead. + +--- + +## Hard Rules + +- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment. +- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough. +- **Stop after the report.** Do not modify the user's project or the target project. +- **HTML is optional.** Do not block analysis on HTML generation. + +## Gotchas + +| What happened | Rule | +|---|---| +| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 | +| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 | +| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` | +| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 | +| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 | +| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 | +| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 | +| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 | +| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 | + +## Outcome + +``` +Essence Report: {project name} +Lens: mechanical / intentional / evolution +Design analyzed: {one-line description} +Files examined: {count} +Pattern: {pattern name or custom description} +Migration: {steal-it example, ≤20 lines} +HTML generated: yes / no +Status: complete +``` + +After the report, stop. No modifications. No follow-ups. diff --git a/skill-workbench/generated-skills/skills/essence/references/essence-signals.md b/skill-workbench/generated-skills/skills/essence/references/essence-signals.md new file mode 100644 index 0000000..b4ad9b8 --- /dev/null +++ b/skill-workbench/generated-skills/skills/essence/references/essence-signals.md @@ -0,0 +1,79 @@ +# Essence Detection Signals + +How to identify the standout design in a project when the user doesn't specify a direction. + +## Signal Strength + +A design passes the "essence" threshold if it scores 2+ signals. + +### Strong Signals (score = 1 each) + +| Signal | How to detect | Example | +|---|---|---| +| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" | +| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` | +| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts | +| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments | +| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning | + +### Objective Signals (score = 1 each, no subjective judgment needed) + +| Signal | How to detect | Example | +|---|---|---| +| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package | +| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic | +| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" | + +### Weak Signals (score = 0.5 each) + +| Signal | How to detect | Example | +|---|---|---| +| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence | +| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" | +| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine | +| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object | + +## Not Signals + +These do NOT count as essence: + +- "Clean code" or "well organized" — that's quality, not design +- "Uses TypeScript" — that's a language choice, not architecture +- "Has good tests" — that's engineering discipline, not design +- "Many stars on the repo" — popularity ≠ design quality +- "Uses the latest framework" — following trends ≠ standing out +- Utility functions — even well-written ones are tools, not designs + +## Auto-detect Procedure + +When the user says "find the essence": + +1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate. +2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate. +3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core. +4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity. +5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently? +6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest. + +### Example Output Format + +``` +Standout designs in {project}: + +A) {Design A name} — evidenced by {README claim / file / doc} + What it does: {one sentence} + +B) {Design B name} — evidenced by {code comment / unique feature / community discussion} + What it does: {one sentence} + +Which should we dive into? (or I can pick the strongest) +``` + +## Failure Modes + +| Situation | Response | +|---|---| +| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." | +| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. | +| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." | +| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." | diff --git a/skill-workbench/generated-skills/skills/explore/SKILL.md b/skill-workbench/generated-skills/skills/explore/SKILL.md new file mode 100644 index 0000000..318a60a --- /dev/null +++ b/skill-workbench/generated-skills/skills/explore/SKILL.md @@ -0,0 +1,87 @@ +--- +name: explore +description: Invoke when you need project-level understanding and an onboarding path. Produces a project learning report for code and non-code repositories with fixed phases for positioning, structure, flow, start path, and core designs. Not for deep code extraction or interactive teaching. +metadata: + version: "0.5.0" +--- + +# Explore: Project Understanding and Onboarding + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a project cartographer. Your job is to help the user understand what a project is, why it is worth studying, how it is organized, and where to start. + +`/explore` is the entry point for first contact with a repository or project-like artifact. It builds global understanding. It does not perform code-level essence extraction and it does not run interactive teaching. + +## Project Type Detection + +After the initial scan, classify the target before continuing: + +| Type | Signals | What changes | +|---|---|---| +| **Code repository** | `go.mod`, `pyproject.toml`, `Cargo.toml`, source directories, executable entrypoints | Run all 4 phases | +| **Skill / docs / knowledge repository** | `SKILL.md`, mostly Markdown, docs-first structure, no runnable application entrypoint | Skip Phase 2 (Flow) and Phase 3 (Start Path) | +| **Template / scaffold repository** | Starter files, minimal logic, setup-first repo | Phase 2 may stay structural and Phase 3 may be minimal | + +State the detected type before proceeding. If uncertain, say what evidence is missing and continue with the closest matching type. + +## Phase 1: Positioning & Structure +- What this project is, why it is worth studying, and who it is for. +- Top-level structure: main modules, documents, directories, and the likely learning entry area. +- Tradeoffs vs alternatives when evidence exists. + +## Phase 2: Flow +**Code repositories only.** +- Skip for non-code and template repositories. +- Trace the main runtime or request flow. +- Produce at least one architecture or core-flow diagram. +- Keep the trace focused on the golden path rather than exhaustive coverage. + +## Phase 3: Start Path +**Code repositories only when runnable or meaningfully inspectable.** +- Provide the minimal path to start learning or running the project. +- Give the first command or first inspection step. +- Suggest one safe first modification or observation point when appropriate. + +## Phase 4: Core Designs +- Summarize 2-3 core implementations or ideas. +- Keep this at overview depth. +- For each item, include what it is, where it lives, and why it matters. + +## Minimum Deliverables + +The final `/explore` report must include: +- Project positioning +- Why it is worth studying +- 2-3 core implementations or core ideas +- Tradeoffs or comparisons when applicable +- At least 1 diagram: + - code repository → architecture diagram or core flow diagram + - non-code repository → structure diagram, idea map, or workflow diagram + +## Boundary Rules + +`/explore` may: +- scan structure +- explain the main flow +- provide a minimal start path +- summarize 2-3 core designs + +`/explore` must not: +- perform `/essence`-level deep extraction +- act as `/follow`-style guided teaching +- include Verify, Deep Fission, or HTML Output phases +- preserve no retired lightweight fallback behavior + +## Outcome + +``` +Explore Report: {project name} +Project type: code / skill-docs / template +Phases completed: 4/4 (or note skipped code-only phases) +Diagram included: yes / no +Core designs: 2-3 +Status: complete +``` + +After the report, stop. Do not proceed to `/essence` or `/follow` automatically. diff --git a/skill-workbench/generated-skills/skills/explore/references/analysis-methods.md b/skill-workbench/generated-skills/skills/explore/references/analysis-methods.md new file mode 100644 index 0000000..f1dcf6a --- /dev/null +++ b/skill-workbench/generated-skills/skills/explore/references/analysis-methods.md @@ -0,0 +1,98 @@ +# Project Analysis Methods + +How to read and understand an unfamiliar code project. + +## 1. Identify the Entry Point + +Every project has a door. Find it first. + +### By Language + +| Language | Look for | +|---|---| +| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` | +| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` | +| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` | +| **Rust** | `src/main.rs` or `src/bin/*.rs` | +| **Java** | Class with `public static void main(String[] args)` | +| **C/C++** | `main()` function, conventionally in `src/main.c` | +| **Swift** | `main.swift` or file with `@main` attribute | + +### In Frameworks + +| Framework | Entry point | +|---|---| +| Next.js | `app/` or `pages/` directory, `next.config.js` | +| React (Vite) | `src/main.tsx` or `src/main.jsx` | +| Vue (Vite) | `src/main.ts` or `src/main.js` | +| Express | File that calls `app.listen()` | +| FastAPI | File that creates `FastAPI()` instance | +| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` | +| Flask | `app.py` or `app/__init__.py` | +| Spring Boot | `*Application.java` with `@SpringBootApplication` | + +## 2. Judge Project Complexity + +Don't over-engineer simple projects. Don't under-analyze complex ones. + +### Simple (<50 files, single language) +- Read every source file. +- No need for flow diagrams beyond a simple sequence. +- A light `/explore` pass is probably enough. + +### Standard (50-500 files, 1-2 languages) +- Read entry point + core modules + 1-2 feature files. +- Build 1-2 flow diagrams. +- `/explore` is the right level. + +### Complex (>500 files, multi-language, monorepo) +- Read entry point + architecture docs + one representative module. +- Use `/essence` to find standout designs, or `/explore` for one package at a time. +- Do NOT try to understand the whole project in one pass. + +## 3. Separate Core Code from Scaffolding + +Not all files are worth reading. + +### Ignore (scaffolding) +- `*.config.js`, `*.config.ts` — configuration, not logic +- `dist/`, `build/`, `out/` — generated output +- `node_modules/`, `vendor/`, `.venv/` — dependencies +- `*.lock`, `yarn.lock`, `go.sum` — lock files +- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta +- `test/fixtures/`, `test/data/` — test data + +### Read (core) +- Entry point file +- Router/middleware/config handlers +- Model/entity/schema definitions +- Core algorithm or business logic files +- Files referenced most in imports + +### Hint: Follow imports + +``` +entry file → import A → import B → core logic +``` + +Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core. + +## 4. Read Unfamiliar Framework Code + +You don't know every framework. That's fine. + +### Strategy + +1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities. + +2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response. + +3. **Identify the framework's conventions.** Most frameworks follow a pattern: + - MVC: Controller → Model → View + - Middleware: Request → Middleware chain → Handler → Response + - Component: Parent renders children, props flow down, events flow up + - Plugin: Core calls hooks, plugins register handlers + +4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose. + +5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented. diff --git a/skill-workbench/generated-skills/skills/explore/references/flow-patterns.md b/skill-workbench/generated-skills/skills/explore/references/flow-patterns.md new file mode 100644 index 0000000..487a5be --- /dev/null +++ b/skill-workbench/generated-skills/skills/explore/references/flow-patterns.md @@ -0,0 +1,173 @@ +# Flow Pattern Library + +Common architecture patterns and how to identify them in code. + +## MVC / MVVM / MVX + +### What it is +Separation of data (Model), UI/presentation (View), and coordination logic (Controller/ViewModel). + +### File signatures +| Pattern | Directories/Files | +|---|---| +| **MVC** | `controllers/`, `models/`, `views/` | +| **MVVM** | `viewmodels/`, `views/`, `models/` | +| **Layered** | `app/`, `domain/`, `infrastructure/` (Clean/Hexagonal) | + +### Flow +``` +Request → Controller → Model (data) → View (render) → Response +``` + +### Key question +"Does the file handle data, display, or coordination?" If yes → MVC-family. + +--- + +## Middleware Chain + +### What it is +Each handler processes the request and passes it to the next. Like an assembly line. + +### File signatures +| Framework | Indicator | +|---|---|---| +| **Express/Koa** | `app.use(...)`, `app.get('/', handler)` | +| **FastAPI** | `@app.middleware("http")`, `Depends()` | +| **Next.js** | `middleware.ts` at root or in `app/` | +| **Gin (Go)** | `router.Use(middleware1, middleware2)` | +| **Koa** | `app.use(async (ctx, next) => { ... })` | + +### Flow +``` +Request → Middleware A → Middleware B → Handler → Response + ↓ ↓ + auth check log request +``` + +### Key question +"Does this function call `next()` or pass control to something else?" If yes → middleware. + +### Common middleware order +``` +1. CORS / Security headers +2. Logging / Request ID +3. Authentication / Authorization +4. Body parsing / Validation +5. Rate limiting +6. Route handler +7. Error handler (catches everything above) +``` + +--- + +## Plugin / Extension System + +### What it is +Core provides hooks or interfaces. External code registers handlers. The core doesn't know about specific plugins. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Hook-based** | `registerHook('eventName', handler)`, `hooks.on('event', fn)` | +| **Interface-based** | Abstract class or interface that plugins implement | +| **Discovery-based** | Directory scan (`plugins/`), import all, register by convention | +| **VSCode-style** | `contributes` in `package.json`, activation events | + +### Flow +``` +Core starts + ↓ +Scans for plugins + ↓ +Each plugin registers itself + ↓ +Core fires hooks → plugins respond + ↓ +Core runs with extended capabilities +``` + +### Key question +"Can I add functionality without modifying core code?" If yes → plugin architecture. + +--- + +## Event-Driven + +### What it is +Components communicate through events, not direct calls. Publishers emit, subscribers listen. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Node EventEmitter** | `eventEmitter.on('event', handler)`, `eventEmitter.emit('event', data)` | +| **Pub/Sub** | `pubsub.subscribe('channel', handler)`, `pubsub.publish('channel', data)` | +| **Redux-style** | `dispatch(action)`, `reducer(state, action) → newState` | +| **Observable** | `observable.subscribe(fn)`, `pipe(map, filter)` | +| **Signals (Python)** | `@signal.connect`, `signal.send()` | + +### Flow +``` +Component A emits "user.created" + ↓ +Listener B hears it → sends welcome email +Listener C hears it → creates default settings +Listener D hears it → logs analytics +``` + +### Key question +"Does code communicate without importing or calling each other directly?" If yes → event-driven. + +--- + +## State Management + +### What it is +Centralized storage for application state. Components read and update through defined interfaces. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Redux** | `createStore()`, `dispatch()`, `useSelector()`, `@reduxjs/toolkit` | +| **Zustand** | `create((set) => ({ ... }))` | +| **Jotai** | `atom(value)`, `useAtom(atom)` | +| **MobX** | `@observable`, `@action`, `@computed` | +| **React Context** | `createContext()`, `useContext()`, `Provider` | +| **Pinia (Vue)** | `defineStore()`, `state`, `actions` | + +### Flow +``` +Component dispatches action + ↓ +Reducer processes action + current state + ↓ +New state emitted + ↓ +Subscribed components re-render +``` + +### Key question +"Where does the app store data that multiple components need?" If it's a single store → state management pattern. + +--- + +## Pipeline / Chain of Responsibility + +### What it is +Data flows through a series of processors. Each processor transforms the data and passes it on. + +### File signatures +| Pattern | Indicator | +|---|---| +| **Stream processing** | `.pipe(transform1).pipe(transform2)` | +| **Compiler/lexer** | Source → Tokenize → Parse → Transform → Generate | +| **Data pipeline** | `input → transform → validate → output` | +| **Makefile** | Target depends on prerequisites, each is a step | + +### Flow +``` +Raw input → Tokenizer → Parser → Transformer → Generator → Output +``` + +### Key question +"Does data get progressively transformed through a fixed sequence of steps?" If yes → pipeline. diff --git a/skill-workbench/generated-skills/skills/explore/scripts/collect-structure.sh b/skill-workbench/generated-skills/skills/explore/scripts/collect-structure.sh new file mode 100644 index 0000000..fe27a78 --- /dev/null +++ b/skill-workbench/generated-skills/skills/explore/scripts/collect-structure.sh @@ -0,0 +1,120 @@ +#!/usr/bin/env bash +# Collect project structure for /explore analysis. +# Usage: Run from project root, or pass project path as argument. +# Output: Structured text with directory tree, file counts, language distribution. + +set -euo pipefail + +PROJECT_DIR="${1:-.}" +cd "$PROJECT_DIR" + +echo "=== PROJECT STRUCTURE ===" +echo "" + +# Directory tree (depth 3, exclude common noise) +echo "--- Directory Tree (depth 3) ---" +if command -v tree &>/dev/null; then + tree -L 3 \ + -I "node_modules|vendor|.git|dist|build|out|.venv|__pycache__|*.egg-info|coverage|.nyc_output" \ + --dirsfirst +elif command -v find &>/dev/null; then + find . -maxdepth 3 \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + -not -path "*/__pycache__/*" \ + -not -path "*/.egg-info/*" \ + -not -path "*/coverage/*" \ + -not -path "./.nyc_output/*" \ + -print | head -100 | sort +fi + +echo "" +echo "=== FILE COUNTS ===" +echo "" + +# Count files by extension (top 10) +echo "--- Top 10 File Types ---" +find . -type f \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + -not -path "*/__pycache__/*" \ + -printf '%f\n' | \ + sed 's/.*\.//' | \ + grep -v '^\.[^/]*$' | \ + sort | uniq -c | sort -rn | head -10 + +echo "" +echo "=== TOTAL FILE COUNT ===" +echo "" + +# Total files (excluding noise) +total=$(find . -type f \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -path "./vendor/*" \ + -not -path "./dist/*" \ + -not -path "./build/*" \ + -not -path "./out/*" \ + -not -path "./.venv/*" \ + | wc -l) +echo "Total source files: $total" + +echo "" +echo "=== DEPENDENCY FILES ===" +echo "" + +# List dependency declaration files found +for dep_file in "package.json" "requirements.txt" "pyproject.toml" "setup.py" "go.mod" "go.sum" "Cargo.toml" "Cargo.lock" "pom.xml" "build.gradle" "Gemfile" "Gemfile.lock" "composer.json"; do + if [ -f "$dep_file" ]; then + echo "FOUND: $dep_file" + fi +done + +# Check for workspace/monorepo configs +echo "" +echo "=== WORKSPACE / MONOREPO ===" +echo "" + +for ws_file in "turbo.json" "nx.json" "lerna.json" "pnpm-workspace.yaml" "go.work"; do + if [ -f "$ws_file" ]; then + echo "FOUND: $ws_file" + fi +done + +# Check Cargo.toml for workspace +if [ -f "Cargo.toml" ] && grep -q '\[workspace\]' Cargo.toml 2>/dev/null; then + echo "FOUND: Cargo.toml [workspace]" +fi + +echo "" +echo "=== ENTRY POINTS ===" +echo "" + +# Try to identify entry points +if [ -f "package.json" ]; then + main=$(node -e "try{const p=require('./package.json');console.log(p.main||'');}catch(e){}" 2>/dev/null || echo "") + bin=$(node -e "try{const p=require('./package.json');console.log(typeof p.bin==='string'?p.bin:JSON.stringify(p.bin));}catch(e){}" 2>/dev/null || echo "") + dev=$(node -e "try{const p=require('./package.json');console.log(p.scripts?.dev||p.scripts?.start||'');}catch(e){}" 2>/dev/null || echo "") + [ -n "$main" ] && echo "package.json main: $main" + [ -n "$bin" ] && echo "package.json bin: $bin" + [ -n "$dev" ] && echo "package.json dev/start: $dev" +fi + +for entry in "src/main.ts" "src/main.tsx" "src/main.js" "src/main.jsx" "src/index.ts" "src/index.js" "src/main.py" "app/main.py" "main.go" "src/main.rs" "app.py" "index.js" "index.ts"; do + if [ -f "$entry" ]; then + echo "FOUND: $entry" + fi +done + +echo "" +echo "=== COLLECTED ===" diff --git a/skill-workbench/generated-skills/skills/follow/SKILL.md b/skill-workbench/generated-skills/skills/follow/SKILL.md new file mode 100644 index 0000000..c6a158c --- /dev/null +++ b/skill-workbench/generated-skills/skills/follow/SKILL.md @@ -0,0 +1,101 @@ +--- +name: follow +description: Invoke when the user wants an interactive learning session based on an existing `/explore` or `/essence` report. Guides runnable or reader-style follow-along sessions. Not for fresh project analysis or pattern-only extraction. +metadata: + version: "0.5.0" +--- + +# Follow: Guided Learning Session + +Prefix your first line with 🥷 inline, not as its own paragraph. + +You are a guide. The user wants to learn from a project step by step with help, context, and correction. You guide the learning process, but you do not replace it. + +`/follow` is not a fresh project analyzer. It only works from an existing `/explore` or `/essence` result. + +## Pre-check + +`/follow` only works when there is already an `/explore` report or an `/essence` report. + +- `/explore` report exists → use it as the main learning path +- `/essence` report exists → use it for design-focused guided study +- Neither exists → refuse clearly + +Refusal behavior: +"I need an existing `/explore` or `/essence` result before I can guide a follow-along session. Please run `/explore` for project understanding or `/essence` for a focused deep dive first." + +Load the existing report before continuing. + +## Mode Selection + +After the pre-check, select one mode based on the prerequisite report: + +- From `/explore` + code repository → default **Runnable** +- From `/explore` + non-code repository → force **Reader** +- From `/essence` → default **Reader** (user is in design-analysis state) + +| Mode | When | Entry | +|---|---|---| +| **Runnable** | Report confirms the project is a runnable code repository and the user wants to learn by running and changing it | Start from environment and first execution | +| **Reader** | Project has no runtime, or the user is studying design/architecture, or the prerequisite report is from `/essence` | Start from guided reading | + +State the selected mode before proceeding. Do not re-scan the project — use the prerequisite report to decide. + +## Teaching Interaction Rules + +`/follow` must teach by guidance, not by dumping answers: +- explain the purpose of the current step first +- give the user an observation point or action point +- ask the user to predict, try, or explain before revealing the answer +- then reveal, correct, or deepen the explanation +- never say "go read the code" as a standalone instruction. When referencing code, always start with: what design idea this code embodies, why it matters in the overall architecture, and what the user should pay attention to + +## Runnable Check + +Before Runnable mode, confirm from the **prerequisite report** (do not re-scan the project): +- If the report identified the target as a code repository with a recognized runtime (`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `build.gradle`, `pom.xml`, `CMakeLists.txt`, etc.), proceed with Runnable. +- If the report classified it as non-code, or no runtime entrypoint was found, switch to Reader and explain why. +- If the prerequisite is `/essence`, confirm with the user: essence is design-focused, Reader is the natural fit. Allow Runnable only if the user explicitly insists. +- Do not introduce a third mode. + +## Runnable Mode Flow +1. Confirm environment and prerequisites. +2. Let the user run the project. +3. Let the user make one safe change. +4. Walk the main flow together. +5. Give one small exercise. +6. Review what they learned. + +## Reader Mode Flow +1. Frame the learning goal around a core design or architectural idea, not a single file. +2. Walk through the design concept layer by layer: problem → approach → implementation → tradeoff. +3. Ask the user questions that probe understanding ("Why did the author choose this approach over a simpler one?"), not just prediction ("What happens next?"). +4. Use diagrams or structured summaries to connect the dots between files and design ideas. +5. Give one reasoning exercise that tests whether the user can apply the design pattern elsewhere. +6. Review what they learned. + +## Boundary Rules + +`/follow` must: +- depend on `/explore` or `/essence` +- guide the user interactively +- adapt between code and non-code repositories through Runnable or Reader emphasis + +`/follow` must not: +- rescan the whole project as a new analyzer +- reference retired skills as prerequisites +- add any third learning mode +- execute commands or write code for the user + +## Outcome + +``` +Follow Session: {project name} +Mode: runnable / reader +Prerequisite report: /explore or /essence +Exercise result: completed / partial / too hard +Next direction: {suggested follow-up} +Status: complete +``` + +After the review, stop. Ask whether the user wants another exercise or wants to end the session. diff --git a/skill-workbench/generated-skills/skills/follow/references/env-detect.md b/skill-workbench/generated-skills/skills/follow/references/env-detect.md new file mode 100644 index 0000000..80ab2af --- /dev/null +++ b/skill-workbench/generated-skills/skills/follow/references/env-detect.md @@ -0,0 +1,113 @@ +# Environment Detection Rules + +How to detect the runtime environment and guide the user through setup in `/follow`. + +## Language Detection from Config + +Check these files in order. The first match is the primary language. + +| Config file | Language | Runtime check | Install command | +|---|---|---|---| +| `package.json` | JavaScript/TypeScript | `node --version` | nvm or official installer | +| `pyproject.toml` | Python | `python --version` | pyenv or python.org | +| `go.mod` | Go | `go version` | golang.org/dl | +| `Cargo.toml` | Rust | `rustc --version` | rustup | +| `pom.xml` | Java | `java -version` | SDKMAN or official | +| `build.gradle` / `build.gradle.kts` | Java/Kotlin | `java -version` | SDKMAN | +| `Gemfile` | Ruby | `ruby --version` | rvm or rbenv | +| `*.csproj` | C#/.NET | `dotnet --version` | .NET SDK | +| `CMakeLists.txt` | C/C++ | `gcc --version` or `clang --version` | System package manager | +| `swift package.json` | Swift | `swift --version` | Xcode or swift.org | + +## Dependency Installation + +Once language is detected, guide the user: + +### JavaScript/TypeScript +```bash +# Check which package manager is used +if [ -f "yarn.lock" ]; then yarn install +elif [ -f "pnpm-lock.yaml" ]; then pnpm install +elif [ -f "bun.lockb" ] || [ -f "bun.lock" ]; then bun install +else npm install +fi +``` + +### Python +```bash +# Modern Python projects +pip install -e . +# Or with requirements +pip install -r requirements.txt +# Or with poetry +poetry install +# Or with uv +uv pip install -r requirements.txt +``` + +### Go +```bash +go mod download +``` + +### Rust +```bash +cargo build +``` + +### Java (Maven) +```bash +mvn install +``` + +### Java (Gradle) +```bash +./gradlew build +# or +gradle build +``` + +## Run Command Detection + +How to start the project: + +| Source | Command | +|---|---| +| `package.json` → `scripts.dev` | `npm run dev` | +| `package.json` → `scripts.start` | `npm start` | +| `Makefile` → `dev` target | `make dev` | +| `Makefile` → `run` target | `make run` | +| `pyproject.toml` (Poetry) | `poetry run python main.py` | +| `go.mod` → `package main` | `go run main.go` | +| `Cargo.toml` → `[[bin]]` | `cargo run` | +| `docker-compose.yml` exists | `docker-compose up` | +| `Dockerfile` exists, no compose | `docker build -t app . && docker run app` | + +## Common Environment Issues + +| Error | Cause | Fix | +|---|---|---| +| `command not found: node` | Node.js not installed | Install Node.js (recommend LTS) | +| `ModuleNotFoundError` | Python deps not installed | Run `pip install -r requirements.txt` | +| `EACCES: permission denied` | Global install without sudo | Use nvm/fnm, or prefix with sudo | +| `ENOENT: no such file` | Wrong working directory | `cd` to project root first | +| `port already in use` | Another process on same port | Kill the process or use different port | +| `go: cannot find main module` | Outside Go module | `cd` to directory with `go.mod` | +| `error: could not find Cargo.toml` | Outside Rust project | `cd` to directory with `Cargo.toml` | +| `java.lang.UnsupportedClassVersionError` | Wrong Java version | Match JDK version to project requirement | +| `npm ERR! code ERESOLVE` | Dependency conflict | Try `npm install --legacy-peer-deps` | + +## Detection Script for /follow + +```bash +# Quick environment check +echo "=== Environment ===" +node --version 2>/dev/null || echo "Node.js: not installed" +python --version 2>/dev/null || echo "Python: not installed" +go version 2>/dev/null || echo "Go: not installed" +rustc --version 2>/dev/null || echo "Rust: not installed" +java -version 2>/dev/null || echo "Java: not installed" +echo "PWD: $(pwd)" +``` + +Run this at the start of `/follow` Step 1 to understand what's available. diff --git a/skill-workbench/generated-skills/sm-flow/SKILL.md b/skill-workbench/generated-skills/sm-flow/SKILL.md new file mode 100644 index 0000000..d22e598 --- /dev/null +++ b/skill-workbench/generated-skills/sm-flow/SKILL.md @@ -0,0 +1,132 @@ +--- +name: sm-flow +description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。 +--- + +# SM Flow + +SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作流。它不替代 OpenSpec，而是用 `devflow/` 中的上下文、术语、PRD、ADR、历史验收和复合知识，辅助生成更准确的 OpenSpec proposal/design/specs/tasks；执行阶段默认依赖 OpenSpec apply；完成后再把结果回填到 `devflow/` 作为长期记忆。 + +## 角色定位 + +你是这条工作流的工程负责人。你的职责不是绕过 OpenSpec 直接写代码，而是确保 OpenSpec 产物足够准确、可执行、可验收，然后以 OpenSpec apply 作为默认执行入口。你需要在关键决策点让用户参与，但仓库阅读、上下文提取、OpenSpec 修正、文档更新和归档提炼应尽量由你完成。 + +## 真理源分层 + +- `devflow/` 是上下文真理源：术语、历史 PRD、ADR、验收记录、复合知识和项目记忆。 +- `openspec/changes//` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。 +- 代码是实现结果：只能在执行真理源足够明确后修改。 +- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。 + +## 核心规则 + +- Phase 3 默认必须通过 OpenSpec apply 执行；禁止直接依赖 devflow 文档绕过 OpenSpec 写代码。 +- devflow 产物只能辅助生成和校准 OpenSpec，不能成为 Phase 3 的主要执行依据。 +- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。 +- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。 +- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。 +- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。 +- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。 +- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。 +- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。 +- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。 +- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。 +- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。 +- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。 +- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。 + +## 首次加载 + +执行前只读取当前任务需要的 reference 文件： + +- 需要逐阶段执行时，读取 `references/phase-contracts.md`。 +- 创建或更新 PRD、ADR、验收报告、词汇表、复合知识文档时，读取 `references/templates.md`。 +- Phase 4 或需要从 OpenSpec 提取产物时，读取 `references/archive-rules.md`。 +- 子 skill 或 OpenSpec skill 无法直接调用时，读取 `references/fallbacks.md`。 + +## 启动检查 + +1. 判断启动模式： + - 完整模式：用户提供粗略想法或初始 PRD。 + - Research 模式：用户已有 research，需要转成或修正 OpenSpec。 + - PRD 文件模式：用户提供已有 PRD 路径。 + - 指定阶段模式：用户要求从某个 Phase 恢复。 + - 快速模式：小改动，Phase 2 和 Phase 4 可以轻量化，但不能省略。 +2. 如果缺少 `devflow/`，初始化： + - `devflow/projects/` + - `devflow/glossary/CONTEXT.md` + - `devflow/compound/` + - `devflow/reference/` +3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。 +4. 检查 OpenSpec 和子 skill 是否可用： + - OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。 + - 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。 +5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。 + +## 项目标识 + +整个流程使用同一个 slug： + +- 优先使用 OpenSpec change name。 +- 如果还没有 change name，则从功能标题生成 kebab-case slug。 +- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。 +- 如果目录已存在，默认恢复该项目，不要重复创建；除非用户明确要求新开一轮。 + +## Devflow 产物分层 + +devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的执行产物。默认只创建必要文件；扩展文件必须有明确理由。 + +**必须产物**： + +- `brief.md`：背景、目标、范围、非目标、变更规模、关联 OpenSpec change。 +- `evidence.md`：代码证据、文档证据、历史决策、evidence-driven 结论和汇报状态。 +- `decisions.md`：user-interview 问题、用户确认、关键取舍、风险接受、OpenSpec 回写记录。 +- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。 + +**按需产物**： + +- `prd.md`：需求复杂、用户明确要求 PRD、或需要对外协作时创建；小需求并入 `brief.md`。 +- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较时创建。 +- `design.md`：仅记录 OpenSpec design 不适合承载的人类背景、架构审计摘要或长期决策索引；实现设计仍以 OpenSpec design 为准。 +- `tasks.md`：仅记录跨轮次追踪或人类复盘任务；执行任务仍以 OpenSpec tasks 为准。 +- `alignment.md` / `clarifications.md`：问题很多或冲突复杂时单独创建；否则并入 `decisions.md`。 +- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR/复合知识规则时创建。 + +**规模分档**： + +- `micro`：小且低风险，使用 `brief.md`、`decisions.md`、`acceptance.md`；证据少时并入 `brief.md`。 +- `standard`：默认模式，使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`。 +- `complex`：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加 PRD/research/design/tasks/alignment。 + +## 阶段总览 + +1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。 +2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。 +3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。 +4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。 +5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。 +6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。 +7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。 +8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。 + +每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。 + +## 快速模式 + +快速模式仅在改动小且低风险时使用。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留： + +- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。 +- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。 +- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。 +- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。 + +## 完成标准 + +一次流程只有在满足以下条件时才算完成： + +- OpenSpec change 中的 proposal/design/specs/tasks 已生成或更新到可执行状态。 +- 实现或规划任务已经完成，且执行依据来自 OpenSpec。 +- 已运行验证，或明确记录未运行验证的原因。 +- `devflow/projects/YYYY-MM-DD-{slug}/` 中存在符合规模分档的必要 devflow 产物，并能说明背景、证据、决策、验收和归档状态。 +- 用户知道剩余风险和下一步动作，并已被询问是否要归档 OpenSpec change。 + diff --git a/skill-workbench/generated-skills/sm-flow/references/archive-rules.md b/skill-workbench/generated-skills/sm-flow/references/archive-rules.md new file mode 100644 index 0000000..a013bfb --- /dev/null +++ b/skill-workbench/generated-skills/sm-flow/references/archive-rules.md @@ -0,0 +1,106 @@ +# 归档规则 + +Phase 4 的目标是把 OpenSpec 产物、实现结果和验证结果转化为持久、可读、可复用的项目记忆。v3 中，OpenSpec 是执行真理源，devflow 是辅助 OpenSpec 和人类阅读的档案层。 + +## 目录规则 + +项目档案路径： + +```text +devflow/projects/YYYY-MM-DD-{slug}/ +``` + +默认创建以下必要文件： + +- `brief.md` +- `evidence.md` +- `decisions.md` +- `acceptance.md` + +按需创建以下扩展文件： + +- `prd.md` +- `research.md` +- `design.md` +- `tasks.md` +- `alignment.md` +- `adr/*.md` + +不要逐字复制完整 OpenSpec 文件，也不要重复 OpenSpec 的 proposal/design/tasks。应提炼 OpenSpec 如何指导执行：背景、证据、用户决策、任务状态、假设、验证结果、风险，以及执行中对 OpenSpec 的修正。 + +## 产物分档 + +| 分档 | 适用场景 | 必须文件 | 扩展文件 | +| --- | --- | --- | --- | +| `micro` | 小改动、低风险、需求明确 | `brief.md`、`decisions.md`、`acceptance.md` | 证据少时并入 `brief.md` | +| `standard` | 默认模式 | `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md` | 按需 ADR/compound | +| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 全部文件 | 按需 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md` | + +## 提取映射 + +| 来源 | 提取内容 | 写入位置 | +| --- | --- | --- | +| `proposal.md` | 为什么做、做什么、范围、非目标 | `brief.md` | +| `design.md` | 技术方案、关键决策、风险；只提炼长期有用内容 | `evidence.md` / 按需 `design.md` | +| `specs/**/*.md` | requirement 标题和 scenario 意图 | `brief.md` 或 `acceptance.md` 的验收追踪 | +| `tasks.md` | checkbox 状态、剩余工作、执行切片 | `acceptance.md`；复杂项目可拆 `tasks.md` | +| 澄清记录 | evidence-driven/user-interview、证据、结论、确认状态 | `evidence.md` + `decisions.md` | +| 测试/构建输出 | 验证命令、结果、验证类型 | `acceptance.md` | +| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` | +| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` | +| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` | + +## 验收记录规则 + +必须真实记录验证情况，并按类型分类： + +- **静态验证**：语法检查、grep/rg 检查、结构检查、类型检查等不运行完整功能的验证。 +- **脚本验证**：生成脚本、测试命令、构建命令、自动化检查等可重复命令。 +- **浏览器/人工验证**：需要用户或代理在界面中点击、观察、确认的行为验证。 +- **未验证**：未运行的验证必须记录原因、风险和建议补验步骤。 + +记录要求： + +- 如果验证通过，记录命令/步骤和覆盖范围。 +- 如果验证失败，记录失败摘要和是否阻塞验收。 +- 如果需要人工验证，列出明确步骤，不要用“手动测试一下”这种模糊描述。 + +## ADR 规则 + +同时满足以下条件时创建 ADR： + +1. 决策难以逆转。 +2. 缺少上下文会让未来维护者困惑。 +3. 决策来自真实权衡，而不是简单偏好。 + +项目内 ADR 存放于： + +```text +devflow/projects/YYYY-MM-DD-{slug}/adr/ +``` + +跨项目可复用决策或经验存放于： + +```text +devflow/compound/YYYY-MM-DD-decision-{slug}.md +``` + +## 归档确认 + +OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 devflow 已经回填 OpenSpec 的关键执行信息： + +- Phase 4 可以建议 archive，但必须先询问用户。 +- 在用户确认前，不要执行 archive。 +- 如果用户暂不归档，在 acceptance 中记录原因或状态。 +- 如果用户确认归档，执行后记录 archive 结果和剩余档案位置。 + +## 归档交接 + +Phase 4 结束时告诉用户： + +- 创建或更新了哪些档案文件。 +- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。 +- 还剩哪些风险或后续事项。 +- 明确询问：是否现在 archive OpenSpec change？ + + diff --git a/skill-workbench/generated-skills/sm-flow/references/fallbacks.md b/skill-workbench/generated-skills/sm-flow/references/fallbacks.md new file mode 100644 index 0000000..64000fb --- /dev/null +++ b/skill-workbench/generated-skills/sm-flow/references/fallbacks.md @@ -0,0 +1,101 @@ +# Fallback 协议 + +当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。 + +## OpenSpec 提案 fallback + +1. 创建或识别 `openspec/changes/{slug}/`。 +2. 先读取 devflow 上下文：`devflow/glossary/CONTEXT.md`、相关项目档案、ADR、acceptance、compound knowledge。 +3. 写入 `proposal.md`，包含： + - 问题 + - 建议方案 + - 范围 + - 非目标 + - 来自 devflow 的上下文约束 + - 风险 +4. 当实现需要技术选择时，写入 `design.md`，并引用相关 ADR 或历史验收结论。 +5. 将 `tasks.md` 写成按纵向切片组织的 checkbox 清单。 +6. 只为外部可见行为或发生变化的需求编写 specs。 +7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。 + +## OpenSpec 修正 fallback + +当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时： + +1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。 +2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。 +3. 向用户汇报冲突和推荐修正。 +4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。 +5. 再同步更新 devflow 文档；不要只改 devflow。 + +## OpenSpec 执行 fallback + +仅当 `openspec-apply-change` 不可调用时使用。执行依据仍必须是 `openspec/changes/{slug}/`。 + +1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。 +2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。 +3. 修改前先检查现有代码。 +4. 一次实现一个 OpenSpec task 的纵向切片。 +5. 用最窄但有效的命令验证每个切片。 +6. 只有验证通过或明确记录原因后，才更新 task 状态。 +7. 如果失败原因不确定，停止并进入 diagnose。 +8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。 + +## PRD fallback + +优先使用 `references/templates.md#brief-模板` 创建 `brief.md`。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 `references/templates.md#prd-模板` 创建 `prd.md`。 + +规则： + +- 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。 +- `brief.md` 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。 +- 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。 + +## 文档化追问 fallback + +1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。 +2. 先声明每个问题的模式：`evidence-driven` 或 `user-interview`。 +3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。 +4. 对 user-interview 问题，一次只问一个并等待用户确认。 +5. 术语确认后立即更新词汇表。 +6. 影响实现的澄清必须回写 OpenSpec。 +7. 只为难以逆转的真实权衡创建 ADR。 + +快速模式的最小问题： + +- 术语：这个概念应该使用哪个领域术语？证据是什么？ +- 边界：哪些内容明确不在范围内？是否需要用户确认？ +- 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？ + +## 架构审计 fallback + +产出一份短架构审计： + +1. 画出输入 → 处理 → 输出。 +2. 列出相关模块和调用方。 +3. 识别耦合、数据所有权和生命周期风险。 +4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。 +5. 用不超过五句话总结最大风险。 +6. 如果影响实现，回写 OpenSpec design/tasks。 + +## Diagnose fallback + +1. 复现问题，或捕获准确失败信息。 +2. 最小化失败案例。 +3. 生成 3-5 个假设，并按可能性和验证成本排序。 +4. 修改代码前，先添加仪器化或定向检查。 +5. 判断根因属于实现问题还是 OpenSpec 规格问题。 +6. 如果是实现问题，修复被证明的最小原因。 +7. 如果是规格问题，先修正 OpenSpec，再继续 apply。 +8. 运行回归验证。 + +## TDD fallback + +使用纵向切片，不要水平批量写测试： + +1. 从 OpenSpec specs 中选择一个外部可见行为。 +2. 写一个失败测试。 +3. 实现刚好让测试通过的最小代码。 +4. 只在测试通过时重构。 +5. 对下一个 OpenSpec 行为重复以上步骤。 + diff --git a/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md b/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md new file mode 100644 index 0000000..0b5b7f6 --- /dev/null +++ b/skill-workbench/generated-skills/sm-flow/references/phase-contracts.md @@ -0,0 +1,199 @@ +# 阶段契约 + +本文件是 SM Flow v3 的逐阶段执行准则。v3 的核心原则是：**devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow**。 + +## Phase 0 — 入口澄清 + +**进入条件**：用户提供粗略想法、初始 PRD、已有 research、issue，或要求启动 SM Flow。 + +**动作**： +- 收集问题、期望结果、目标用户、涉及代码区域、约束条件和可能的非目标。 +- 如果用户已有 research，先识别它是否已经包含用户价值、技术方案、验收标准和任务拆分。 +- 如果输入过于模糊，最多追加三轮聚焦问题。 +- 当答案会改变 OpenSpec proposal/specs/tasks 时，优先一次只问一个问题。 + +**退出条件**： +- 问题可以用 1-2 句话说清楚。 +- 期望结果可以用 1-2 句话说清楚。 +- 已列出已知影响代码或模块；如果未知，也明确标记。 +- 可以生成 OpenSpec change slug。 + +**输出**： +- 入口摘要。 +- 初步 slug。 +- devflow 规模分档：`micro` / `standard` / `complex`。 + +## Phase 0.5 — Devflow 上下文收集 + +**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。 + +**动作**： +- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。 +- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。 +- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。 +- 记录哪些上下文会影响 OpenSpec proposal/design/specs/tasks。 +- 如果发现旧根目录 `CONTEXT.md` 与 `devflow/glossary/CONTEXT.md` 冲突，暂停并向用户汇报。 + +**退出条件**： +- 已形成“OpenSpec 输入上下文摘要”。 +- 已列出相关 ADR 和不能违反的历史决策。 +- 已列出需要写入或修正 OpenSpec 的上下文点。 + +**输出**： +- 上下文摘要，默认写入 `brief.md` 或 `evidence.md`；会影响实现的上下文必须写入 OpenSpec design/specs/tasks。 + +## Phase 1 — OpenSpec propose + +**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。 + +**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。 + +**动作**： +- 优先调用 `openspec-propose`。 +- 如果不可用，执行 `references/fallbacks.md#openspec-propose-fallback`，但仍必须产出 OpenSpec 文件。 +- 用 Phase 0.5 的 devflow 上下文增强 OpenSpec： + - proposal 写清为什么做、做什么、范围和非目标。 + - design 写入上下文约束、历史 ADR、关键技术决策。 + - specs 写成可验收的外部行为。 + - tasks 写成可执行的纵向切片。 +- 在承诺设计细节前，先检查相关仓库代码。 + +**退出条件**： +- `openspec/changes//proposal.md` 存在。 +- 对需要正式 OpenSpec 产物的变更，`design.md`、`tasks.md` 和 specs 存在。 +- 关键假设已显式记录在 OpenSpec 或 research 中。 + +**输出**： +- OpenSpec proposal、design、specs 和 task list。 + +**Human checkpoint**： +- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。 +- 询问是否继续进入 PRD/OpenSpec 对齐和澄清阶段；用户明确要求“全自动执行”时可跳过等待。 + +## Phase 1.5 — PRD / OpenSpec 对齐 + +**进入条件**：Phase 1 已有 OpenSpec 产物。 + +**显式子 skill**：`to-prd` + `sm-flow`。进入本阶段必须先声明是否读取 `.agents/skills/to-prd/SKILL.md`；如果使用内置模板，标记为 PRD fallback。 + +**动作**： +- 如果没有结构化 PRD，则优先按 `to-prd` 协议生成 `brief.md`；复杂需求、对外协作或用户明确要求时再生成 `prd.md`。 +- `micro` 模式默认不创建独立 PRD，除非用户要求或需求复杂度升级；PRD 内容并入 `brief.md`。 +- 检查 PRD、devflow 上下文和 OpenSpec 是否一致： + - OpenSpec 是否覆盖 PRD 的用户故事和验收预期。 + - OpenSpec 是否使用 glossary 中的正确术语。 + - OpenSpec 是否遵守相关 ADR。 + - specs 是否能表达可观察行为。 + - tasks 是否能驱动实现，而不是泛泛描述。 +- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。 + +**退出条件**： +- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。 +- OpenSpec 与 PRD/devflow 上下文没有已知冲突。 +- 所有已知冲突已修正或等待用户决策。 + +**输出**： +- `brief.md`，以及按需创建的 `prd.md`。 +- OpenSpec 对齐检查记录。 +- 必要的 OpenSpec 修正。 + +## Phase 2 — Human-in-the-loop 澄清 + +**进入条件**：已有 OpenSpec 产物和 PRD/上下文对齐记录。 + +**显式子 skill**：`grill-with-docs`。进入本阶段必须先声明是否读取 `.agents/skills/grill-with-docs/SKILL.md`；fallback 必须标记为“文档化追问 fallback”。 + +**动作**： +- 优先使用 `grill-with-docs`。 +- 先声明本阶段采用的澄清模式，并逐项标记： + - `evidence-driven`：问题能通过代码、文档、测试、OpenSpec 或既有 ADR 证明；代理先查证，再向用户汇报证据、结论和是否需要确认。 + - `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。 +- 至少覆盖三个维度：术语、边界、验收。 +- 一次只问一个 `user-interview` 问题。 +- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。 +- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。 +- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。 + +**退出条件**： +- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。 +- 所有 evidence-driven 结论已向用户汇报。 +- 所有 user-interview 决策已获得用户确认。 +- 影响实现的结论已回写 OpenSpec。 + +**输出**： +- 澄清记录：默认写入 `decisions.md`；问题很多时可拆出 `clarifications.md`。记录术语、边界、验收三个维度、模式、证据、结论、用户确认状态。 +- 更新后的 OpenSpec。 +- 更新后的词汇表和 ADR。 + +## Phase 2.5 — 架构审计 + +**进入条件**：Phase 2 已解决主要产品、领域和验收问题。 + +**显式子 skill**：`zoom-out`。进入本阶段必须先声明是否读取 `.agents/skills/zoom-out/SKILL.md`；fallback 必须标记为“架构审计 fallback”。 + +**动作**： +- 画出输入 → 处理 → 输出的模块链路。 +- 识别跨模块依赖、数据所有权、生命周期和耦合风险。 +- 检查是否与既有架构、ADR、OpenSpec design 冲突。 +- 用不超过五句话写出架构风险评估。 +- 如果审计结果影响实现，必须回写 OpenSpec design/tasks；只写入 devflow design 不够。 + +**退出条件**： +- 架构风险已被接受，或流程返回 Phase 2/Phase 1 修正 OpenSpec。 +- OpenSpec design/tasks 已反映会影响实现的架构审计结论。 + +**输出**： +- 架构审计记录，默认写入 `decisions.md` 或 `evidence.md`；复杂架构审计可拆出 `design.md`。 +- 必要的 OpenSpec design/tasks 修正。 + +**Human checkpoint**： +- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。 +- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。 + +## Phase 3 — OpenSpec apply + +**进入条件**： +- `openspec/changes//` 中 proposal/design/specs/tasks 已达到可执行状态。 +- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。 +- devflow 与 OpenSpec 没有未解决冲突。 + +**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。 + +**动作**： +- 优先调用 `openspec-apply-change`。 +- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。 +- 按 OpenSpec tasks 的纵向切片实现。 +- 当用户要求、行为复杂或回归风险高时使用 TDD。 +- 当测试失败、行为意外或原因不确定时使用 diagnose。 +- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。 +- 修改文件前遵守仓库指令，例如 `AGENTS.md`。 + +**退出条件**： +- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。 +- 已运行验证，或记录了未验证原因。 +- 已列出已知限制。 + +**输出**： +- 代码变更、必要测试和实现说明。 +- 更新后的 OpenSpec task 状态。 + +## Phase 4 — 回填 Devflow + +**进入条件**：实现或规划工作已经达到可交接状态。 + +**显式子 skill**：`openspec-archive-change` 只在用户确认 archive 后调用；Phase 4 回填由 `sm-flow` 执行。必须记录 archive 是真实调用还是手动 fallback。 + +**动作**： +- 遵循 `references/archive-rules.md`。 +- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。 +- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。 +- 如果本次流程产生可复用经验，写入 compound knowledge。 +- 询问用户是否要 archive OpenSpec change；不要默认执行归档。 + +**退出条件**： +- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。 +- 用户已被询问是否 archive OpenSpec change。 + +**输出**： +- 默认输出 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`；按需输出 `prd.md`、`research.md`、`design.md`、`tasks.md`、`alignment.md`、ADR 和 compound knowledge。 + diff --git a/skill-workbench/generated-skills/sm-flow/references/templates.md b/skill-workbench/generated-skills/sm-flow/references/templates.md new file mode 100644 index 0000000..e9b6885 --- /dev/null +++ b/skill-workbench/generated-skills/sm-flow/references/templates.md @@ -0,0 +1,290 @@ +# 模板 + +这些是最小模板。只有在能提升未来可读性时，才增加额外章节。保留 PRD、ADR、OpenSpec、slug 等行业术语，其余说明尽量使用中文。 + +## Brief 模板 + +```markdown +# {标题} Brief + +## 背景 + +- 用户目标：{goal} +- 当前问题：{problem} +- 关联 OpenSpec：`openspec/changes/{slug}/` +- devflow 分档：micro | standard | complex + +## 范围 + +- 本次要做：{in scope} +- 本次不做：{out of scope} +- 影响区域：{modules/files if known} + +## OpenSpec 对齐 + +- proposal 覆盖状态：已覆盖 / 待修正 / 不适用 +- specs 覆盖状态：已覆盖 / 待修正 / 不适用 +- tasks 覆盖状态：已覆盖 / 待修正 / 不适用 +``` + +## Evidence 模板 + +```markdown +# {标题} Evidence + +## 证据 + +| 来源 | 证据 | 结论 | 是否已汇报 | +| --- | --- | --- | --- | +| {file/doc/test/ADR} | {evidence summary} | {conclusion} | 是 / 否 | + +## Evidence-driven 结论 + +- 结论：{conclusion} + - 证据：{evidence} + - 风险：{risk if any} + - 用户确认：需要 / 不需要 / 已确认 +``` + +## Decisions 模板 + +```markdown +# {标题} Decisions + +## User-interview + +| 问题 | 用户回答 | 决策 | OpenSpec 回写 | +| --- | --- | --- | --- | +| {question} | {answer} | {decision} | 已回写 / 不影响 / 待回写 | + +## 关键取舍 + +- 决策：{decision} + - 原因：{why} + - 影响：{impact} + - 风险接受：{accepted by whom/when} +``` + +## PRD 模板 + +```markdown +# {标题} PRD + +## 问题陈述 + +用用户视角描述问题。 + +## 解决方案 + +用用户视角描述预期解决方案。 + +## 用户故事 + +1. 作为{角色}，我希望{能力}，以便{收益}。 + +## 实现决策 + +- 决策：{decision} + - 原因：{why} + - 影响：{affected modules or behavior} + +## 测试决策 + +- 好测试应该通过{public interface}验证{observable behavior}。 +- 必须覆盖：{critical paths} +- 不测试：{explicit exclusions} + +## 非目标 + +- {excluded behavior} + +## 补充说明 + +- {open question or useful context} +``` + +## 词汇表模板 + +```markdown +# 上下文词汇表 + +## 术语 + +### {术语} + +- 定义：{precise definition} +- 使用场景：{feature/module/context} +- 备注：{ambiguities, synonyms, or rejected meanings} + +## 业务规则 + +- {rule}: {meaning and source} +``` + +## ADR 模板 + +```markdown +# ADR-{编号}: {决策标题} + +**状态**：提议中 | 已接受 | 已废弃 +**日期**：YYYY-MM-DD + +## 背景 + +是什么情况迫使我们做这个决策？ + +## 决策 + +我们选择了什么？ + +## 替代方案 + +| 方案 | 拒绝原因 | +| --- | --- | +| {option} | {reason} | + +## 后果 + +### 正面 + +- {benefit} + +### 负面 + +- {cost or risk} +``` + +## 技术调研模板 + +```markdown +# {标题} 技术调研 + +## 摘要 + +- 变更原因：{reason} +- 变更范围：{scope} +- 主要技术方案：{approach} + +## 源产物 + +- OpenSpec change: `openspec/changes/{slug}/` +- 关联 PRD: `prd.md` 或 `brief.md` + +## 关键发现 + +- {finding} + +## 假设 + +- {assumption and validation status} +``` + +## 设计模板 + +```markdown +# {标题} 设计 + +## 架构摘要 + +描述输入 → 处理 → 输出。 + +## 关键决策 + +- {decision}: {reason} + +## 模块地图 + +| 模块 | 职责 | 备注 | +| --- | --- | --- | +| {module} | {responsibility} | {notes} | + +## 架构审计 + +- 风险：{risk} +- 缓解：{mitigation} +``` + +## 任务模板 + +```markdown +# {标题} 任务 + +## 需求追踪 + +| 需求 | 状态 | 备注 | +| --- | --- | --- | +| {requirement} | 已完成 / 待处理 / 部分完成 | {notes} | + +## 实现任务 + +- [ ] {task} +``` + +## 验收模板 + +```markdown +# {标题} 验收 + +## 结果 + +已接受 / 部分接受 / 未接受。 + +## 验证 + +### 静态验证 + +- 命令/检查：`{command or check}` +- 结果：{passed/failed/not run} +- 备注：{important output or reason not run} + +### 脚本验证 + +- 命令：`{command}` +- 结果：{passed/failed/not run} +- 备注：{important output or reason not run} + +### 浏览器/人工验证 + +- 步骤：{manual steps} +- 结果：{passed/failed/not run} +- 备注：{observations or reason not run} + +## 已完成范围 + +- {completed behavior} + +## 已知限制 + +- {limitation} + +## Bug 修复和诊断 + +- {bug}: {diagnosis summary and regression coverage} + +## 交接 + +- 下一步：{archive, deploy, review, or follow-up} +- OpenSpec 归档确认：{已询问/用户确认归档/用户暂不归档/不适用} +``` + +## 复合知识模板 + +```markdown +# {标题} + +**类型**：learning | trick | decision | explore +**日期**：YYYY-MM-DD + +## 背景 + +这条经验来自哪里？ + +## 经验 + +未来代理应该复用什么经验？ + +## 适用性 + +什么时候适用？什么时候不适用？ +``` + diff --git a/skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md b/skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md new file mode 100644 index 0000000..b4dfd81 --- /dev/null +++ b/skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md @@ -0,0 +1,136 @@ +# Skills v0.5.0 整合修复记录 + +**日期：** 2026-04-30 +**来源：** grill-me 逐项审查，基于 v0.5.0 changelog 和 design doc 对比实际实现发现的不一致 + +--- + +## 一句话摘要 + +在前次 v0.5.0 slim architecture 改造的基础上，逐文件对比 design doc、proposal、plan、实际实现，修复了 `/essence` 遗漏项、`/follow` 旧引用残留、`/explore` 阶段冗余、references 死文件、docs 目录垃圾等问题。 + +--- + +## 已完成的改动 + +### 1. `/essence` — 补齐 v0.5.0 改造（之前遗漏） + +| 位置 | 修改内容 | +|---|---| +| 版本号 | `0.3.0` → `0.5.0` | +| 透镜定义 | 删除 `(borrowed from /explore)`，声明为 `/essence` 自有 | +| 透镜相关 Phase 2/3/4/5 表格 | 从独立 3 列表格瘦身为内联 bullet point | +| HTML Card | `## Phase 6: Output (Optional HTML Card)` → `## Optional: HTML Card`；去 "production-critical" 条件，改为 `Only when the user explicitly requests it` | +| HTML Card 死链接 | 删除 `Same as /explore.` 两处，改为自包含内容 | +| Mode Selection 上下文感知 | 新增检测逻辑：来自 `/explore` → 默认 User-directed；独立启动 → 默认 Auto-detect | +| Auto-detect 信号 | `Most imported file` → `Cross-module contract`（后端项目更准确） | + +### 2. `/follow` — 消除旧引用和设计偏差 + +| 位置 | 修改内容 | +|---|---| +| Mode Selection | 新增前置报告感知：来自 `/explore` + 代码仓库 → Runnable；来自 `/explore` + 非代码 → Reader；来自 `/essence` → Reader | +| Runnable Check | 删除重新扫描逻辑，改为从前置报告读取结论；运行时信号改为后端导向（`go.mod`, `pyproject.toml`, `Cargo.toml`, `Makefile` 等） | +| Reader Mode Flow | 从文件级 "Walk one core file" 提升为设计级 "Frame the learning goal around a core design" | +| 教学规则 | `do not use "go read the code" as the default instruction without context` → `never say "go read the code" as a standalone instruction`；引用代码必须先交代设计上下文 | + +### 3. `/explore` — 合并冗余阶段 + +| 位置 | 修改内容 | +|---|---| +| Phase 1+2 | `Phase 1: Positioning` + `Phase 2: Structure` 合并为 `Phase 1: Positioning & Structure` | +| 阶段总数 | 5 Phase → 4 Phase | +| Project Type Detection | 信号列表同步（`package.json` 不再为首例）；阶段跳过的编号更新 | +| Outcome 模板 | `5/5` → `4/4` | + +### 4. References 清理 + +| 文件 | 操作 | +|---|---| +| `skills/explore/references/deep-fission.md` | **删除** — 描述已移除的 Deep Fission 功能，引用不存在的 `/fission` 技能 | +| `skills/essence/references/essence-signals.md` | `Most imported file` → `Cross-module contract`，与 SKILL.md 同步 | + +### 5. docs 存档清理 + +| 文件 | 操作 | 原因 | +|---|---|---| +| `docs/superpowers/proposal.md` | 删除 | 原始 4-skill 提案，已过时 | +| `docs/superpowers/plan.md` | 删除 | 实施模板与实际实现不一致 | +| `docs/superpowers/plans/` | 删除 | 456 行 task-by-task 计划，含 `/map` 引用 | +| `docs/superpowers/README.md` | 删除 | `superpowers/README.md` 的副本，不属于历史存档 | + +--- + +## docs 存档最终结构 + +``` +docs/superpowers/ +├── specs/ +│ ├── issue.md # 原始需求 +│ ├── 2026-04-21-skills-v0.5.0-slim-architecture-design.md +│ └── 2026-04-21-skills-v0.5.0-changelog-design.md +└── changelog/ + ├── 2026-04-21-skills-v0.5.0-slim-architecture.md # 第一次改造 changelog + ├── 2026-04-21-skills-v0.5.0-validation-handoff.txt # 交接指令 + └── 2026-04-30-skills-v0.5.0-consolidation.md # 本次整合（本文件） +``` + +--- + +## 当前 skill 状态 + +| 技能 | 版本 | Phase/Mode | 备注 | +|---|---|---|---| +| `/explore` | v0.5.0 | 4 Phase | 支持代码/非代码仓库；合并 Positioning+Structure | +| `/essence` | v0.5.0 | 5 Phase + Optional HTML | 透镜自有；上下文感知 Mode Selection | +| `/follow` | v0.5.0 | Runnable / Reader | 来源感知；不再重新扫描项目 | + +--- + +## 实践验证结果 + +**日期：** 2026-04-30 +**测试目标仓库：** +- 非代码仓库：explore-skill-family（自身） +- 代码仓库：SuperBizAgent-java（Spring Boot + AI Agent） + +| # | 验证路径 | 目标 | 结果 | +|---|---|---|---| +| 1 | `/follow` 拒绝无前置报告 | 直接模拟 | ✅ | +| 2 | `/explore` 非代码仓库 | 自身 skill family | ✅ — 正确识别 skill-docs，跳过 Flow/Start | +| 3 | `/essence` 深挖 | "硬边界"设计 | ✅ — 结论-证据-解释，可迁移 | +| 4 | `/explore` → `/follow` | 自身 | ✅ — Reader 分流，引用报告内容 | +| 5 | `/essence` → `/follow` | 自身 | ✅ — design-focused，未重扫 | +| 6 | 三技能职责边界 | 综合矩阵检查 | ✅ — 核心问题/深度/前置依赖/产出均无重叠 | +| 7 | `/explore` 代码仓库 | SuperBizAgent-java | ✅ — 4 Phase 全流程，后端信号检测正常 | + +### 验证发现的额外修复 + +验证过程中对 SKILL.md 的追加修改（已在代码中反映）： +- `/essence` Phase 6 → Optional: HTML Card +- `/essence` Mode Selection 上下文感知 +- `/essence` Most imported file → Cross-module contract +- `/follow` Mode Selection 来源感知 +- `/follow` Runnable Check 不再重扫，引用前置报告 +- `/follow` Reader Mode Flow 提升到设计层 +- `/follow` Teaching Interaction Rules 收紧 +- `/explore` Phase 1+2 合并，5→4 Phase +- `/explore` Project Type Detection 信号改为后端导向 +- 删除 `skills/explore/references/deep-fission.md` + +### handoff 10 条检查清单逐项结论 + +| # | 问题 | 结论 | +|---|---|---| +| 1 | `/explore` 对代码/非代码给出不同输出？ | ✅ Phase 2/3 对非代码跳过 | +| 2 | `/explore` 保持在项目级理解？ | ✅ Phase 4 概览深度 | +| 3 | `/essence` 稳定找最高价值设计？ | ✅ "硬边界"提取到 pattern 层 | +| 4 | `/follow` 无前置报告明确拒绝？ | ✅ 拒绝并引导 | +| 5 | `/follow` 基于 /explore 或 /essence 结果？ | ✅ 两次测试均基于前置报告 | +| 6 | `/follow` 避免重新扫描？ | ✅ 三次验证均未重扫 | +| 7 | `/follow` 真正引导式教学？ | ✅ 先问后讲 | +| 8 | 三技能职责重叠/模糊？ | ✅ 边界清晰 | +| 9 | README 与实际行为一致？ | ✅ 三技能描述与 SKILL.md 一致 | +| 10 | references 与 v0.5.0 一致？ | ✅ deep-fission 已删，signals 已同步 | + +**总体验收结论：通过。** 文档、边界、行为三者一致。 diff --git a/skill-workbench/history/docs/adr/0001-directory-name-as-truth-source.md b/skill-workbench/history/docs/adr/0001-directory-name-as-truth-source.md new file mode 100644 index 0000000..b502ad7 --- /dev/null +++ b/skill-workbench/history/docs/adr/0001-directory-name-as-truth-source.md @@ -0,0 +1,39 @@ +# ADR-001: 目录名作为日期和标题的真理源 + +**状态**：已接受 +**日期**：2026-05-18 + +## 背景 + +知识吸收器输出目录遵循 `knowledge_YYYYMMDD_Title/` 命名约定。目录内的 `.md` 文件包含 YAML frontmatter，其中也有 `date`/`created` 和 `title` 字段，但实际使用中发现字段名不一致（`date` vs `created`）和格式差异。 + +索引重建脚本需要确定日期和标题的权威来源。 + +## 决策 + +**日期和短标识符 (slug) 的真理源是目录名。显示标题、tags、author 的真理源是 YAML frontmatter。** + +- 日期从目录名的 `YYYYMMDD` 部分提取 +- 短标识符从目录名的 `Slug` 部分提取（用于文件路径构建，不用于显示） +- 显示标题从 YAML frontmatter 的 `title` 字段提取 +- `tags` 和 `author` 从 YAML frontmatter 提取 + +## 替代方案 + +| 方案 | 被拒原因 | +|------|---------| +| YAML 全优先 | 字段名不一致（date vs created） | +| 目录名全优先 | 标题中的语义信息在下划线转空格后丢失（如 `mattpocock_skills` → `mattpocock skills`，实际标题更长更精确） + +## 后果 + +### 正面 +- 索引脚本不需要处理日期字段名变体（date vs created） +- 目录名是可见的、可审计的——与 `ls` 输出完全一致 +- bash 用 glob 匹配 `knowledge_*` 目录，天然获取了日期和 slug +- 显示标题从 YAML 取，支持完整的、精确的标题文本（含标点、中文） + +### 负面 +- 索引脚本需要解析 YAML frontmatter（复杂度比仅取目录名高） +- 如果目录被重命名，slug 会变化但显示标题不受影响（可接受的行为） +- 知识吸收器 skill 必须严格遵守 `knowledge_YYYYMMDD_Slug` 命名约定 diff --git a/skill-workbench/history/docs/agents/knowledge-index-panel-prd.md b/skill-workbench/history/docs/agents/knowledge-index-panel-prd.md new file mode 100644 index 0000000..5d05d46 --- /dev/null +++ b/skill-workbench/history/docs/agents/knowledge-index-panel-prd.md @@ -0,0 +1,57 @@ +# PRD: 知识库索引面板 (Knowledge Index Panel) + +## Problem Statement + +用户每次用 `/knowledge-absorber` 学习后，会在项目根目录生成 `knowledge_YYYYMMDD_Title/` 文件夹。目前有 2 个知识条目，预计每月增长 5-10 个。所有条目散落在根目录，没有跨条目的导航或搜索能力。想找之前学过的内容只能手动翻目录，搜索成本随条目数线性上升。 + +## Solution + +在项目根目录生成一个 **纯静态的 `knowledge-index.html`**，浏览器直接打开即可使用。它能自动发现所有 knowledge 条目，提供标签关联和全文搜索。不需要任何服务器、数据库或外部依赖。 + +## User Stories + +1. As a 学习者, I want to see all my knowledge entries on one page with dates, so that I can quickly find what I studied and when +2. As a 学习者, I want to search across all knowledge entries by keyword, so that I can find "that thing about Redis" in 2 seconds instead of manually opening 10 folders +3. As a 学习者, I want to click a tag like "Claude Code" and see all related entries, so that I can review interconnected topics +4. As a 学习者, I want the index to auto-discover new knowledge entries, so that I don't need to manually update anything after running `/knowledge-absorber` +5. As a 学习者, I want the page to work offline by just double-clicking the HTML file, so that I can use it without internet or any setup +6. As a 学习者, I want to see which entries are related to each other via shared tags, so that I can discover connections between topics I've studied +7. As a 学习者, I want the search to highlight matching text, so that I can see at a glance why an entry matched my query +8. As a 学习者, I want to see a count of entries per tag, so that I know which topics I've studied most + +## Implementation Decisions + +- **Single HTML file**: All CSS and JS inlined in `knowledge-index.html`. No external files or CDN dependencies +- **Manifest-based discovery**: A JavaScript array inside the HTML lists all known knowledge directory names. Browser security sandbox prevents dynamic directory listing via `fetch()` +- **YAML frontmatter parsing**: Regex-based extraction from `.md` files. Simple key:value parsing only — no full YAML spec support +- **Client-side search**: All `.md` content loaded into memory at page init. Real-time filtering with `String.includes()`, case-insensitive. `` tags for highlighting +- **Tag system**: In-memory `Map` built at load time. Click to filter, click again to deselect +- **Related Content**: Computed from shared tags, displayed per-entry +- **No pagination**: Designed for < 50 entries. Full list rendered at once +- **UTF-8 encoding**: All files assumed UTF-8. `fetch()` handles encoding detection + +## Testing Decisions + +- **What makes a good test**: Test external behavior — "user types keyword → correct entries appear" — not internal state +- **Test with real data**: Use existing 2 knowledge entries (`knowledge_20260417_Waza`, `knowledge_20260518_mattpocock_skills`) as test fixtures +- **Edge cases to verify**: + - Missing directory (manifest lists a name that doesn't exist) → skip gracefully + - Malformed YAML → display directory name as fallback + - Empty tags array → no tag badges rendered + - No search results → show "没有找到相关条目" message + - Browser CORS when opened via `file://` protocol → document the workaround + +## Out of Scope + +- Google Drive / cloud sync +- Editing knowledge entries +- Full YAML 1.2 spec compliance +- Pagination or virtual scrolling +- Fuse.js or other fuzzy search libraries (keep it zero-dependency) +- Dark mode toggle (can add later, not in v1) + +## Further Notes + +- The manifest maintenance problem (adding new entries) can be solved in a future iteration by modifying the `/knowledge-absorber` skill to auto-append to the manifest array +- The `file://` protocol CORS limitation on Chrome means users may need to serve via `python -m http.server` or similar for full functionality +- Tag counts provide a natural "learning heatmap" — most-studied topics bubble to the top diff --git a/skill-workbench/validation/skills-lock.json b/skill-workbench/validation/skills-lock.json new file mode 100644 index 0000000..bb9c6b8 --- /dev/null +++ b/skill-workbench/validation/skills-lock.json @@ -0,0 +1,35 @@ +{ + "version": 1, + "skills": { + "diagnose": { + "source": "mattpocock/skills", + "sourceType": "github", + "skillPath": "skill-workbench/validation/project/skills/skills/engineering/diagnose/SKILL.md", + "computedHash": "1c3c85517ac42116fe5f2bfb5150f7b3e38ad23808e40b33fbb01f1afb611983" + }, + "grill-with-docs": { + "source": "mattpocock/skills", + "sourceType": "github", + "skillPath": "skill-workbench/validation/project/skills/skills/engineering/grill-with-docs/SKILL.md", + "computedHash": "499b742470fe169976bacdba2f30d7a6a25b526629cb42ab21dfa06e1eb286dc" + }, + "tdd": { + "source": "mattpocock/skills", + "sourceType": "github", + "skillPath": "skill-workbench/validation/project/skills/skills/engineering/tdd/SKILL.md", + "computedHash": "78b31b2120c5fe7aced1cebfd4c7c94acb0037fd4f89c83c67584414aa4173bd" + }, + "to-prd": { + "source": "mattpocock/skills", + "sourceType": "github", + "skillPath": "skill-workbench/validation/project/skills/skills/engineering/to-prd/SKILL.md", + "computedHash": "a80acb8760af6521a37ea4f079e617712fcaa800f8a766e247f815c5dabb20d2" + }, + "zoom-out": { + "source": "mattpocock/skills", + "sourceType": "github", + "skillPath": "skill-workbench/validation/project/skills/skills/engineering/zoom-out/SKILL.md", + "computedHash": "a8b8ed45609fdfa9f184d0c9f69326e43822a42eebea14db2792d777373de562" + } + } +} diff --git a/skill-workbench/validation/tmp2/lumina-essence-report.md b/skill-workbench/validation/tmp2/lumina-essence-report.md new file mode 100644 index 0000000..c88042b --- /dev/null +++ b/skill-workbench/validation/tmp2/lumina-essence-report.md @@ -0,0 +1,216 @@ +# Essence 报告：AI Pipeline 架构 + +**项目：** Lumina +**Lens（透镜）：** Mechanical（技术实现） +**设计分析：** Article AI Pipeline Service +**文件数：** 6 个核心文件 +**状态：** 完成 + +--- + +## 定位 + +** standout design：** 模块化 AI 内容处理管道，支持配置化 Prompt 和 Model。 + +**为什么值得学：** +- 解决「AI 处理步骤硬编码」的通病 +- 结构化输出协议可复用到其他 AI 项目 +- 任务状态机设计可迁移到任意异步处理系统 + +--- + +## 核心文件 + +| 文件 | 角色 | 关键内容 | +|------|------|----------| +| `article_ai_pipeline_service.py:102` | Pipeline 编排器 | `ArticleAIPipelineService` 主类 | +| `article_ai_pipeline_service.py:114` | 输出契约定义 | `STRUCTURED_OUTPUT_CONTRACTS` | +| `article_ai_pipeline_service.py:2039` | 清洗阶段 | `process_article_cleaning` | +| `article_ai_pipeline_service.py:3567` | AI 内容生成 | `process_ai_content` | +| `task_state.py:1` | 状态机 | `ALLOWED_TASK_STATUS_TRANSITIONS` | + +--- + +## Call Chain 调用链 + +``` +submit_article(url) + │ + ▼ +┌─────────────────────────┐ +│ ingest_service │ +│ - fetch raw HTML │ +└───────────┬─────────────┘ + │ + ▼ +┌─────────────────────────┐ ┌─────────────────────────┐ +│ process_article_cleaning│────▶│ process_article_validate│ +│ - 清洗原始内容为 Markdown│ │ - 验证内容合规性 │ +└───────────┬─────────────┘ └───────────┬─────────────┘ + │ │ + │ ▼ + │ ┌─────────────────────────┐ + │ │ process_article_classify│ + │ │ - 自动分类 │ + │ └───────────┬─────────────┘ + │ │ + ▼ ▼ +┌─────────────────────────┐ ┌─────────────────────────┐ +│ process_article_tagging │ │ 其他 AI 任务... │ +│ - 自动打标签 │ │ │ +└───────────┬─────────────┘ └─────────────────────────┘ + │ + ▼ +┌─────────────────────────┐ +│ process_ai_content │ +│ - summary/key_points/ │ +│ quotes/outline/ │ +│ infographic │ +└─────────────────────────┘ +``` + +--- + +## 核心设计模式 + +### 1. 结构化输出契约（Structured Output Contract） + +**文件:** `article_ai_pipeline_service.py:114-205` + +```python +STRUCTURED_OUTPUT_CONTRACTS = { + "classification": PromptOutputContract( + mode="structured_json", + response_format={ + "type": "json_schema", + "json_schema": { + "name": "article_classification_result", + "schema": {"type": "object", "properties": { + "category_id": {"type": "string"} + }, "required": ["category_id"]} + } + }, + system_instruction="固定输出协议：必须返回单个 JSON 对象..." + ), + # ... tagging, validation, outline +} +``` + +**作用：** 将「AI 输出格式不稳定的」问题在系统设计层面解决，不再依赖 Prompt Engineering。 + +### 2. 可配置 Prompt + Model 绑定 + +**文件:** `article_ai_pipeline_service.py:255-334` + +**查询优先级：** +1. 传入的 `model_config_id` / `prompt_config_id` +2. Category 级别的配置 +3. 全局默认配置 + +**迁移价值：** +- 无需重启服务即可切换模型 +- A/B 测试不同 Prompt 效果 +- 支持多模型混用（强项模型处理特定任务） + +### 3. Pipeline 状态机 + +**文件:** `task_state.py:12-23` + +```python +ALLOWED_TASK_STATUS_TRANSITIONS = { + TASK_STATUS_PENDING: {TASK_STATUS_PROCESSING, TASK_STATUS_CANCELLED}, + TASK_STATUS_PROCESSING: { + TASK_STATUS_PENDING, TASK_STATUS_COMPLETED, TASK_STATUS_FAILED + }, + TASK_STATUS_FAILED: {TASK_STATUS_PENDING}, # 支持重试 + TASK_STATUS_CANCELLED: {TASK_STATUS_PENDING}, # 取消后可恢复 +} +``` + +**扩展点：** 状态流转规则集中定义，新增状态只需改一行。 + +### 4. 续写/修复机制 + +**文件:** `article_ai_pipeline_service.py:3567-3598` + +```python +async def process_ai_content( + self, + article_id: str, + content_type: str, + continuation_source_usage_id: str | None = None, # 续写源头 + continuation_feedback: str | None = None, # 用户反馈 + ... +): +``` + +**设计意图：** 不是一轮生成完事，而是支持「反馈 → 修复 → 续写」的迭代循环。 + +--- + +## Pattern 分析 + +| 维度 | 内容 | +|------|------| +| **问题** | 如何为同一篇文章批量生成摘要、标签、分类、翻译等 AI 内容？ | +| **模式** | 配置驱动的 Pipeline + 结构化输出契约 | +| **替代方案** | A) 每个功能独立 endpoint，各自调用 AI（重复配置）；B) 固定流程硬编码（不可配置） | +| **Tradeoff** | 放弃实时性（Pipeline 异步执行），换取可配置性和失败隔离 | +| **证据** | `article_ai_pipeline_service.py:102-205` 定义契约；`task_state.py:1-60` 状态机 | + +--- + +## Migration 示例（可执行） + +**场景：** 为自己的项目实现「User Content → AI Processed Content」管道。 + +```python +# pipeline.py - 核心骨架（≤20 行） +from dataclasses import dataclass +from typing import Callable + +@dataclass +class PipelineStep: + name: str + processor: Callable[[str], str] + output_type: str = "text" + +class ContentPipeline: + def __init__(self): + self.steps: list[PipelineStep] = [] + + def add_step(self, step: PipelineStep): + self.steps.append(step) + + async def process(self, content: str) -> dict: + results = {"input": content} + for step in self.steps: + results[step.name] = await step.processor(results.get(step.output_type, content)) + return results + +# 使用 +pipeline = ContentPipeline() +pipeline.add_step(PipelineStep("clean", clean_html, "text")) +pipeline.add_step(PipelineStep("summarize", generate_summary, "clean")) +``` + +--- + +## Pitfalls 陷阱 + +| 陷阱 | 原因 | 规避方法 | +|------|------|----------| +| AI 输出格式不稳定 | 未定义结构化契约 | 复制 `STRUCTURED_OUTPUT_CONTRACTS` 思想 | +| Pipeline 某步失败导致整体失败 | 无状态隔离 | 每步独立状态，失败可重试 | +| Prompt 调优困难 | Prompt 与代码耦合 | 数据库存储，支持按 category 配置 | +| 成本不可控 | 无 Token 统计 | 每步记录 `price_input_per_1k` / `price_output_per_1k` | + +--- + +## 证据核对 + +- [x] 设计真实存在（`article_ai_pipeline_service.py:102`） +- [x] 文件列表 ≤ 10（实际 6 个） +- [x] Pattern 可解释（配置驱动 + 结构化契约） +- [x] Migration ≤ 20 行（上面示例 19 行） +- [x] Pitfalls 具体（有代码/配置对应） diff --git a/skill-workbench/validation/tmp2/lumina-explore-report-optimized.md b/skill-workbench/validation/tmp2/lumina-explore-report-optimized.md new file mode 100644 index 0000000..2efc99c --- /dev/null +++ b/skill-workbench/validation/tmp2/lumina-explore-report-optimized.md @@ -0,0 +1,235 @@ +# Explore 报告：Lumina（优化版） + +**项目类型：** 代码仓库 +**完成阶段：** 5/5 +**包含图示：** 是 +**核心设计：** 3 个 +**状态：** 完成 + +--- + +## 阶段 1：定位 + +**是什么：** Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。 + +**为什么值得学习：** +- 完整的内容处理 AI Pipeline 架构 +- 领域驱动分层设计，关注点分离清晰 +- 支持多租户的内容管理，内置治理功能 + +**目标用户：** 需要构建自托管知识库或 AI 增强 CMS 的开发者。 + +--- + +## 阶段 2：结构 + +``` +lumina-main/ +├── backend/ # FastAPI Python 后端 +│ ├── app/ +│ │ ├── api/routers/ # 16 个 REST 端点模块 +│ │ ├── domain/ # 业务逻辑层 ⭐ +│ │ ├── core/ # 配置与依赖 +│ │ └── schemas/ # Pydantic 数据模型 +│ ├── alembic/ # 数据库迁移 +│ ├── ai_client.py # AI 客户端抽象 +│ └── models.py # SQLAlchemy ORM 定义 +└── frontend/ # Next.js React 前端 + └── src/ + ├── app/ # App Router 结构 + └── components/ # 可复用 UI 组件 +``` + +**入口点：** +- 后端：`backend/app/domain/` - 业务逻辑 +- 前端：`frontend/src/app/(routes)/` - 页面路由 + +--- + +## 阶段 3：流程（优化版 - 黄金路径视角） + +### 端到端用户流程图 + +``` +用户视角: +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ 输入URL │──────▶│ 等待处理 │──────▶│ 查看文章 │ +└──────────────┘ └──────────────┘ └──────────────┘ + +系统视角: +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ API接收请求 │──────▶│ URL获取内容 │──────▶│ 内容清洗 │ +└──────────────┘ └──────────────┘ └───────┬──────┘ + │ +┌──────────────┐ ┌──────────────┐ ┌───────▼──────┐ +│ 向量存储 │◀────│ 信息提取 │◀────│ AI处理链 │ +└──────────────┘ └──────────────┘ └──────────────┘ + │ + ▼ + ┌──────────────┐ + │ 响应用户 │ + └──────────────┘ +``` + +### 模块调用链 + +**文章导入完整调用链：** + +``` +POST /api/articles/ingest + │ + ▼ +┌──────────────────────────────────────┐ +│ article_router.py │ +│ - 接收 URL payload │ +└──────────────┬───────────────────────┘ + │ + ▼ +┌──────────────────────────────────────┐ +│ article_url_ingest_service.py │ +│ - 获取原始 HTML │ +└──────────────┬───────────────────────┘ + │ + ▼ +┌──────────────────────────────────────┐ +│ article_ai_pipeline_service.py │ +│ ┌──────────────┬──────────────┐ │ +│ │ clean_text │ extract_tags │ │ +│ └──────────────┴──────────────┘ │ +│ ┌──────────────┬──────────────┐ │ +│ │ summarize │ embed │ │ +│ └──────────────┴──────────────┘ │ +└──────────────┬───────────────────────┘ + │ + ▼ +┌──────────────────────────────────────┐ +│ article_command_service.py │ +│ - 持久化到数据库 │ +└──────────────────────────────────────┘ +``` + +**优化点说明：** +- 原报告只展示了 `pipeline_service` 单文件内部流程 +- 优化版增加了**用户视角的端到端流程**和**完整的模块调用链** +- 让读者理解从 URL 到数据库的完整路径，不只是中间某个环节 + +--- + +## 阶段 4：起步路径（优化版 - 可执行命令） + +**前置要求：** +- Python 3.11+ +- PostgreSQL + +**步骤 1：环境准备** +```bash +cd backend +pip install -e . +``` + +**步骤 2：数据库初始化** +```bash +alembic upgrade head +``` + +**步骤 3：启动服务** +```bash +uvicorn app.main:app --reload +``` + +**首个观察点：** +打开 `backend/app/api/routers/article_router.py`，搜索 `ingest` 端点，观察： +- 接收什么参数（URL、可选的 category_id） +- 调用哪个 service 方法 +- 返回什么响应 + +**第一个可执行的修改（颗粒度细化）：** + +原报告只说了"修改 AI_MODEL"，没有具体命令。以下是可落地的步骤： + +```bash +# 1. 复制示例配置文件 +cp backend/.env.example backend/.env + +# 2. 查看当前 AI 模型设置 +grep AI_MODEL backend/.env +# 输出: AI_MODEL=gpt-3.5-turbo + +# 3. 修改为其他模型（举例） +sed -i 's/AI_MODEL=.*/AI_MODEL=gpt-4o-mini/' backend/.env + +# 4. 确认修改成功 +grep AI_MODEL backend/.env +# 输出: AI_MODEL=gpt-4o-mini + +# 5. 重启服务（如果已运行） +# Ctrl+C 停止，然后重新运行: +uvicorn app.main:app --reload + +# 6. 验证：测试 AI 摘要功能 +# 在浏览器打开: http://localhost:8000/docs +# 找到 POST /api/articles/ingest，Try it out +# 输入: {"url": "https://example.com/article"} +# 观察响应中的 summary 字段质量变化 +``` + +**安全边界：** +- 只改 `.env` 文件，不动源码 +- 随时可以 `cp backend/.env.example backend/.env` 恢复 +- 改模型不影响数据库，只影响 AI 调用 + +--- + +## 阶段 5：核心设计 + +| # | 设计 | 位置 | 重要性 | +|---|------|------|--------| +| 1 | **领域服务层** | `app/domain/*.py` | API 与数据库解耦；AI 集成可独立演进 | +| 2 | **AI Pipeline 架构** | `article_ai_pipeline_service.py` | AI 处理不耦合 ORM；可配置、可追踪 | +| 3 | **路由注册器** | `api/router_registry.py` | 集中注册；新增模块无需改动 main.py | + +--- + +## 架构图示 + +**后端领域架构：** + +``` +┌─────────────────────────────────────────┐ +│ API 路由层 │ +│ (article, ai_tasks, auth, settings...) │ +└──────────────────┬──────────────────────┘ + │ +┌──────────────────▼──────────────────────┐ +│ 领域服务层 │ +│ ┌──────────────┐ ┌──────────────────┐ │ +│ │article_query │ │article_command │ │ +│ └──────────────┘ └──────────────────┘ │ +│ ┌──────────────┐ ┌──────────────────┐ │ +│ │ai_pipeline │ │ingest_service │ │ +│ └──────────────┘ └──────────────────┘ │ +└──────────────────┬──────────────────────┘ + │ +┌──────────────────▼──────────────────────┐ +│ SQLAlchemy 模型层 │ +└─────────────────────────────────────────┘ +``` + +--- + +## 优化点总结 + +| 优化项 | 原报告 | 优化版 | 改进原因 | +|--------|--------|--------|----------| +| Phase 3 流程 | 单文件内部流程 | 端到端用户流程 + 完整调用链 | 让读者理解全貌，不只是某个环节 | +| Phase 4 修改 | "修改 AI_MODEL"（笼统） | 给具体命令：copy → sed → grep → 重启 → 测试 | 用户可直接执行，有验证环节 | + +--- + +## 验证备注 + +- 按 v0.5.0 规范完成 5 个阶段 +- 未进行 essence 级别的深度提取 +- 未进行交互式教学 +- 遵守边界规则 +- Phase 4 的修改建议已通过 `sed` 命令细化到可操作级别 diff --git a/skill-workbench/validation/tmp2/lumina-explore-report.md b/skill-workbench/validation/tmp2/lumina-explore-report.md new file mode 100644 index 0000000..c77484b --- /dev/null +++ b/skill-workbench/validation/tmp2/lumina-explore-report.md @@ -0,0 +1,134 @@ +# Explore 报告：Lumina + +**项目类型：** 代码仓库 +**完成阶段：** 5/5 +**包含图示：** 是 +**核心设计：** 3 个 +**状态：** 完成 + +--- + +## 阶段 1：定位 + +**是什么：** Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。 + +**为什么值得学习：** +- 完整的内容处理 AI Pipeline 架构 +- 领域驱动分层设计，关注点分离清晰 +- 支持多租户的内容管理，内置治理功能 + +**目标用户：** 需要构建自托管知识库或 AI 增强 CMS 的开发者。 + +--- + +## 阶段 2：结构 + +``` +lumina-main/ +├── backend/ # FastAPI Python 后端 +│ ├── app/ +│ │ ├── api/routers/ # 16 个 REST 端点模块 +│ │ ├── domain/ # 业务逻辑层 ⭐ +│ │ ├── core/ # 配置与依赖 +│ │ └── schemas/ # Pydantic 数据模型 +│ ├── alembic/ # 数据库迁移 +│ ├── ai_client.py # AI 客户端抽象 +│ └── models.py # SQLAlchemy ORM 定义 +└── frontend/ # Next.js React 前端 + └── src/ + ├── app/ # App Router 结构 + └── components/ # 可复用 UI 组件 +``` + +**入口点：** +- 后端：`backend/app/domain/` - 业务逻辑 +- 前端：`frontend/src/app/(routes)/` - 页面路由 + +--- + +## 阶段 3：流程 + +**核心流程：文章导入 → AI 处理 → 存储** + +``` +┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ +│ URL 提交 │────▶│ ingest_service │────▶│ Router │ +└─────────────┘ └──────────────────┘ └──────┬──────┘ + │ +┌─────────────┐ ┌──────────────────┐ │ +│ 响应 │◀────│ pipeline_service │◀──────────┘ +└─────────────┘ └──────────────────┘ + │ + ▼ + ┌─────────────┐ + │ ORM │ + └─────────────┘ +``` + +**关键文件：** `backend/app/domain/article_ai_pipeline_service.py` - 模块化 AI 处理链，支持可配置步骤（清洗 → 打标签 → 摘要 → 嵌入）。 + +--- + +## 阶段 4：起步路径 + +**前置要求：** +- Python 3.11+ +- PostgreSQL + +**设置命令：** +```bash +cd backend +pip install -e . +alembic upgrade head # 初始化数据库模式 +uvicorn app.main:app --reload # 启动开发服务器 +``` + +**首个观察点：** 在 router 中查看 `article_ai_pipeline_service.py` 的调用链。 + +**安全的首个修改：** 修改 `core/settings.py` 中的 `AI_MODEL`，观察不同的 AI 行为。 + +---kanyii + +## 阶段 5：核心设计 + +| # | 设计 | 位置 | 重要性 | +|---|------|------|--------| +| 1 | **领域服务层** | `app/domain/*.py` | API 与数据库解耦；AI 集成可独立演进 | +| 2 | **AI Pipeline 架构** | `article_ai_pipeline_service.py` | AI 处理不耦合 ORM；可配置、可追踪 | +| 3 | **路由注册器** | `api/router_registry.py` | 集中注册；新增模块无需改动 main.py | + +--- + +## 架构图示 + +**后端领域架构：** + +``` +┌─────────────────────────────────────────┐ +│ API 路由层 │ +│ (article, ai_tasks, auth, settings...) │ +└──────────────────┬──────────────────────┘ + │ +┌──────────────────▼──────────────────────┐ +│ 领域服务层 │ +│ ┌──────────────┐ ┌──────────────────┐ │ +│ │article_query │ │article_command │ │ +│ └──────────────┘ └──────────────────┘ │ +│ ┌──────────────┐ ┌──────────────────┐ │ +│ │ai_pipeline │ │ingest_service │ │ +│ └──────────────┘ └──────────────────┘ │ +└──────────────────┬──────────────────────┘ + │ +┌──────────────────▼──────────────────────┐ +│ SQLAlchemy 模型层 │ +└─────────────────────────────────────────┘ +``` + +--- + +## 验证备注 + +- 按 v0.5.0 规范完成 5 个阶段 +- 未进行 essence 级别的深度提取 +- 未进行交互式教学 +- 遵守边界规则