feat: add frontend development guidelines and structure documentation
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
This commit is contained in:
yuxuanhui
Vendored
+1
@@ -0,0 +1 @@
|
||||
{}
|
||||
Vendored
+1
@@ -0,0 +1 @@
|
||||
{}
|
||||
Vendored
+33
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"file-explorer": true,
|
||||
"global-search": true,
|
||||
"switcher": true,
|
||||
"graph": true,
|
||||
"backlink": true,
|
||||
"canvas": true,
|
||||
"outgoing-link": true,
|
||||
"tag-pane": true,
|
||||
"footnotes": false,
|
||||
"properties": true,
|
||||
"page-preview": true,
|
||||
"daily-notes": true,
|
||||
"templates": true,
|
||||
"note-composer": true,
|
||||
"command-palette": true,
|
||||
"slash-command": false,
|
||||
"editor-status": true,
|
||||
"bookmarks": true,
|
||||
"markdown-importer": false,
|
||||
"zk-prefixer": false,
|
||||
"random-note": false,
|
||||
"outline": true,
|
||||
"word-count": true,
|
||||
"slides": false,
|
||||
"audio-recorder": false,
|
||||
"workspaces": false,
|
||||
"file-recovery": true,
|
||||
"publish": false,
|
||||
"sync": true,
|
||||
"bases": true,
|
||||
"webviewer": false
|
||||
}
|
||||
Vendored
+217
@@ -0,0 +1,217 @@
|
||||
{
|
||||
"main": {
|
||||
"id": "d19c0cdf9102d9c7",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "95aa7b7e869f44b5",
|
||||
"type": "tabs",
|
||||
"children": [
|
||||
{
|
||||
"id": "06ba3753fa958e03",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "markdown",
|
||||
"state": {
|
||||
"file": "AI-RD-Workflow/40-workflows/ai-development-workflow.md",
|
||||
"mode": "source",
|
||||
"source": false
|
||||
},
|
||||
"icon": "lucide-file",
|
||||
"title": "ai-development-workflow"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "vertical"
|
||||
},
|
||||
"left": {
|
||||
"id": "5fe384f14e03c3e4",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "f7eedaca65d3f70a",
|
||||
"type": "tabs",
|
||||
"children": [
|
||||
{
|
||||
"id": "81dfd388c3bb5590",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "file-explorer",
|
||||
"state": {
|
||||
"sortOrder": "alphabetical",
|
||||
"autoReveal": false
|
||||
},
|
||||
"icon": "lucide-folder-closed",
|
||||
"title": "文件列表"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "701f12abcaebf21c",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "search",
|
||||
"state": {
|
||||
"query": "",
|
||||
"matchingCase": false,
|
||||
"explainSearch": false,
|
||||
"collapseAll": false,
|
||||
"extraContext": false,
|
||||
"sortOrder": "alphabetical"
|
||||
},
|
||||
"icon": "lucide-search",
|
||||
"title": "搜索"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "eb0851bdba76966a",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "bookmarks",
|
||||
"state": {},
|
||||
"icon": "lucide-bookmark",
|
||||
"title": "书签"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "horizontal",
|
||||
"width": 300
|
||||
},
|
||||
"right": {
|
||||
"id": "b660d769a23129bb",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "8b787905c862e2c6",
|
||||
"type": "tabs",
|
||||
"children": [
|
||||
{
|
||||
"id": "59554c5b8d6b2e63",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "backlink",
|
||||
"state": {
|
||||
"collapseAll": false,
|
||||
"extraContext": false,
|
||||
"sortOrder": "alphabetical",
|
||||
"showSearch": false,
|
||||
"searchQuery": "",
|
||||
"backlinkCollapsed": false,
|
||||
"unlinkedCollapsed": true
|
||||
},
|
||||
"icon": "links-coming-in",
|
||||
"title": "反向链接"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "0103e62bba5012a4",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "outgoing-link",
|
||||
"state": {
|
||||
"linksCollapsed": false,
|
||||
"unlinkedCollapsed": true
|
||||
},
|
||||
"icon": "links-going-out",
|
||||
"title": "出链"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "78b54c55df1c9d88",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "tag",
|
||||
"state": {
|
||||
"sortOrder": "frequency",
|
||||
"useHierarchy": true,
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-tags",
|
||||
"title": "标签"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "4715e42f6395fb0d",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "all-properties",
|
||||
"state": {
|
||||
"sortOrder": "frequency",
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-archive",
|
||||
"title": "添加笔记属性"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "52b794694b381ae6",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "outline",
|
||||
"state": {
|
||||
"followCursor": false,
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-list",
|
||||
"title": "大纲"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "horizontal",
|
||||
"width": 300,
|
||||
"collapsed": true
|
||||
},
|
||||
"left-ribbon": {
|
||||
"hiddenItems": {
|
||||
"switcher:打开快速切换": false,
|
||||
"graph:查看关系图谱": false,
|
||||
"canvas:新建白板": false,
|
||||
"daily-notes:打开/创建今天的日记": false,
|
||||
"templates:插入模板": false,
|
||||
"command-palette:打开命令面板": false,
|
||||
"bases:新建数据库": false
|
||||
}
|
||||
},
|
||||
"active": "81dfd388c3bb5590",
|
||||
"lastOpenFiles": [
|
||||
"docs/MonoProxy订阅信息获取工作流.md",
|
||||
"AI-RD-Workflow/40-workflows/pm-workflow.md",
|
||||
"AI-RD-Workflow/40-workflows/rd-workflow.md",
|
||||
"AI-RD-Workflow/40-workflows/se-workflow.md",
|
||||
"AI Coding/AI-RD-Workflow/40-workflows/trellis-matt/workflow.md",
|
||||
"AI Coding/AI-RD-Workflow/40-workflows/trellis-matt/AGENTS.md",
|
||||
"AI-RD-Workflow/40-workflows/trellis-matt/CN",
|
||||
"AI-RD-Workflow/00-meta/artifact-model.md",
|
||||
"AI-RD-Workflow/20-skills/pm-requirement-refine/SKILL.md",
|
||||
"AI-RD-Workflow/20-skills/rd-design-generate/SKILL.md",
|
||||
"AI-RD-Workflow/20-skills/pm-requirement-review/SKILL.md",
|
||||
"AI-RD-Workflow/00-meta/glossary.md",
|
||||
"AI-RD-Workflow/00-meta/naming-conventions.md",
|
||||
"AI-RD-Workflow/10-standards/review-gates.md",
|
||||
"AI-RD-Workflow/10-standards/lifecycle.md",
|
||||
"AI-RD-Workflow/00-meta/roadmap.md",
|
||||
"AI-RD-Workflow/30-templates/intake.md",
|
||||
"AI-RD-Workflow/30-templates/ds.md",
|
||||
"AI-RD-Workflow/30-templates/dr.md",
|
||||
"AI Coding/inbox/20260627-cloud-runtime-project-root.md",
|
||||
"AI Coding/inbox/20260715-codegraph-before-impact-analysis.md",
|
||||
"AI Coding/inbox/20260715-codegraph-first-for-cross-file-analysis.md",
|
||||
"AI Coding/inbox/20260625-central-compounding-brain.md",
|
||||
"AI Coding/inbox/index.md",
|
||||
"docs/MidScene 配置.md",
|
||||
"AI Coding/assets/index.md",
|
||||
"AI Coding/learnings/index.md",
|
||||
"docs",
|
||||
"notes",
|
||||
"projects",
|
||||
"people"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
- 把 ~/vault 当作你长期的工作记忆区。
|
||||
- 尽量把笔记整理得有条理，别搞得到处都是碎片记录。
|
||||
- 准确地把待办事项、人员、项目、每日总结和草稿分类放好。
|
||||
- 把做过的决定、遇到的卡点、负责人、日期和有用的链接好好保存下来。
|
||||
- 如果没有什么实质性的新进展，不要随意修改知识库里的文件。
|
||||
@@ -0,0 +1,13 @@
|
||||
# Assets
|
||||
|
||||
索引由成熟经验产生的可执行资产：
|
||||
|
||||
- global-agents
|
||||
- repo-agents
|
||||
- skills
|
||||
- hooks
|
||||
- scripts
|
||||
- evals
|
||||
- templates
|
||||
|
||||
资产的实际 source of truth 可以在对应项目或 `~/.agents/skills` 中；这里记录来源 learning、目标路径和验证方式。
|
||||
@@ -0,0 +1,5 @@
|
||||
# Experiments
|
||||
|
||||
记录可复现的模型、提示词、上下文、工具和工作流实验。
|
||||
|
||||
每个实验至少包含假设、输入、对照、观察指标、结果和结论。不要把单次主观感受直接提升为 Pattern。
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: 20260625-central-compounding-brain
|
||||
title: 使用中央知识仓库管理跨项目 AI coding 经验
|
||||
created: 2026-06-25
|
||||
updated: 2026-06-25
|
||||
status: candidate
|
||||
scope: global
|
||||
category: agent-workflows
|
||||
confidence: medium
|
||||
last_verified: 2026-06-25
|
||||
promotion_target: skill
|
||||
projects:
|
||||
- personal-codex
|
||||
tags:
|
||||
- compound-engineering
|
||||
- knowledge-management
|
||||
- cross-project
|
||||
---
|
||||
|
||||
# 使用中央知识仓库管理跨项目 AI coding 经验
|
||||
|
||||
## Trigger
|
||||
|
||||
多个项目分别积累 AI coding 经验，导致相同纠正、失败路径和成功模式难以跨项目检索与复用。
|
||||
|
||||
## Context
|
||||
|
||||
当前 Obsidian Vault 被选为个人跨项目复利仓库。全局 Skill 负责工作流，Vault 负责持续增长的经验数据，各项目继续保留与代码版本强关联的执行规则。
|
||||
|
||||
## Evidence
|
||||
|
||||
- 2026-06-25：确定采用中央大脑与项目执行层分离的架构。
|
||||
- 全局 Skill 位于 `~/.agents/skills/compound-coding/`。
|
||||
- 中央知识入口位于 `AI Coding/index.md`。
|
||||
|
||||
## Root cause
|
||||
|
||||
经验如果只保留在单次对话或单个项目中，就无法稳定跨项目检索；如果所有规则都集中在全局提示中，又会造成上下文膨胀并污染项目边界。
|
||||
|
||||
## Preferred action
|
||||
|
||||
将新经验先写入中央 `inbox/`，验证后进入 `learnings/`，跨项目成立后再归纳为 `patterns/`。把确定性要求同步为项目测试、lint、hook、脚本或 `AGENTS.md`。
|
||||
|
||||
## Boundaries
|
||||
|
||||
- 项目专属架构、命令和业务事实仍以项目仓库为准。
|
||||
- 中央经验在使用前需要根据当前代码和文档重新验证。
|
||||
- 不把凭证、客户数据或其他敏感信息写入复利仓库。
|
||||
|
||||
## Promotion record
|
||||
|
||||
- 2026-06-25：创建全局 `compound-coding` Skill 作为工作流执行层；候选经验仍需经过实际项目使用验证。
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
id: 20260627-cloud-runtime-project-root
|
||||
title: 云端运行时不要依赖 process.cwd() 推断项目根目录
|
||||
created: 2026-06-27
|
||||
updated: 2026-06-27
|
||||
status: candidate
|
||||
scope: global
|
||||
category: debugging
|
||||
confidence: high
|
||||
last_verified: 2026-06-27
|
||||
promotion_target: none
|
||||
projects:
|
||||
- evaluator-agent
|
||||
tags:
|
||||
- cloud-deployment
|
||||
- path-resolution
|
||||
- playwright
|
||||
- diagnostics
|
||||
---
|
||||
|
||||
# 云端运行时不要依赖 process.cwd() 推断项目根目录
|
||||
|
||||
## Trigger
|
||||
|
||||
本地测试能读到配置或资源，但部署到云端后同一流程表现为配置缺失、鉴权未执行、文件不存在、资源路径 404，且日志里只看到后续业务失败。
|
||||
|
||||
## Context
|
||||
|
||||
一次 Playwright 云端测试排查中，测试进程能访问目标页面，但前置鉴权没有执行，页面最终停留在登录页。最初怀疑是 cookie/sessionStorage 写入失败、Chrome 限制或跨域问题。后来通过运行时证据确认：fixture 已经执行，但没有读到项目 auth 配置。
|
||||
|
||||
关键差异是云端 Playwright 进程的 `process.cwd()` 是应用包目录，而项目文件和 `.evaluator/projects/<id>.json` 在另一个工作目录。代码用 `process.cwd()` 推断项目根目录，导致读取了错误位置的配置文件。
|
||||
|
||||
## Evidence
|
||||
|
||||
- 2026-06-26/27，`evaluator-agent` 云端测试排查。
|
||||
- 运行时 `auth-setup` 证据显示：`projectIdPresent=true`，但 `authConfigured=false`，`authApplied=false`。
|
||||
- 临时深度诊断曾显示运行时尝试读取 `/app/.evaluator/projects/<project-id>.json`，但实际项目产物位于 `/workspace/project/...`。
|
||||
- 修复提交：`ee1e9b0 Fix Playwright project root resolution for auth config`。
|
||||
- 相关文件：
|
||||
- `packages/core/src/evaluator/run.ts`：启动 Playwright 时传入 `EVALUATOR_PROJECT_ROOT=projectRoot`。
|
||||
- `packages/playwright/src/fixtures/ai-test.ts`：fixture 读取配置时使用 `EVALUATOR_PROJECT_ROOT || process.cwd()`。
|
||||
- `.trellis/spec/frontend/run-analysis-contracts.md`：记录云端 cwd 与项目根目录可能不同的契约。
|
||||
- 清理提交：`8547bd1 chore: remove temporary auth debug diagnostics`，保留稳定布尔证据，删除过细路径/配置探测字段。
|
||||
|
||||
## Root cause
|
||||
|
||||
已验证原因：云端运行进程的 cwd 不等于项目根目录。配置读取逻辑把 `process.cwd()` 当作项目根，导致读取错误路径，表现为配置不存在。
|
||||
|
||||
推断：类似问题也可能发生在测试报告、静态资源、项目级配置、凭证文件、生成产物、fixture 初始化、CLI 子进程中，只要代码通过 cwd 隐式推导项目根。
|
||||
|
||||
## Preferred action
|
||||
|
||||
对需要部署到云端或由子进程执行的代码：
|
||||
|
||||
1. 显式传递项目根目录，例如 `PROJECT_ROOT` / `EVALUATOR_PROJECT_ROOT`，而不是在下游模块里直接信任 `process.cwd()`。
|
||||
2. 子进程启动处负责设置这个 env；fixture、worker、CLI helper 只读取显式根目录并保留 `process.cwd()` 作为本地直跑 fallback。
|
||||
3. 在运行产物里记录低风险、结构化的健康检查字段，例如 `projectIdPresent`、`authConfigured`、`authApplied`，用于远程确认流程是否执行。
|
||||
4. 临时深度诊断可以短期记录路径、config existence 等字段定位问题，但修复后应清理，避免长期暴露内部部署结构。
|
||||
5. 把这个约束写成项目契约或测试，防止以后又退回 cwd 推断。
|
||||
|
||||
## Boundaries
|
||||
|
||||
- 本地单进程脚本、一次性维护脚本、明确从仓库根执行的工具可以使用 `process.cwd()`，但要把这个前提写清楚。
|
||||
- 不要把密码、token、cookie 值、请求 body/header 值写入诊断产物。
|
||||
- 路径诊断是否保留要看用户场景：短期排查可以详细，长期产品化证据应收敛到必要布尔状态和可操作错误摘要。
|
||||
|
||||
## Failed approaches
|
||||
|
||||
- 先排查 cookie/sessionStorage、CORS、Chrome flags 和页面 JS 错误，虽然有价值，但没有直接回答“fixture 是否读到配置”。
|
||||
- 临时把 `configPath`、`configFilePresent`、`projectRoot` 等字段加入运行时证据能快速定位问题，但不适合作为长期默认产物。
|
||||
- 不推荐把配置复制到云端 cwd 对应目录；这会形成两份配置，后续 UI、测试和服务端可能读到不同来源。
|
||||
|
||||
## Promotion record
|
||||
|
||||
- Not promoted.
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: 20260715-codegraph-before-impact-analysis
|
||||
title: 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
|
||||
created: 2026-07-15
|
||||
updated: 2026-07-15
|
||||
status: candidate
|
||||
scope: global
|
||||
category: agent-workflows
|
||||
confidence: medium
|
||||
last_verified: 2026-07-15
|
||||
promotion_target: none
|
||||
projects:
|
||||
- oppein-react-component
|
||||
tags:
|
||||
- codegraph
|
||||
- impact-analysis
|
||||
- dependency-context
|
||||
- agent-workflows
|
||||
---
|
||||
|
||||
# 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
|
||||
|
||||
## Trigger
|
||||
|
||||
项目启用了 CodeGraph，且任务涉及跨包、跨目录或跨组件理解，调用链排查，重构、重命名、删除，或修改共享 API、类型、导出、hooks、服务接口和工具；也适用于需要评估回归范围或应补充哪些测试的任务。
|
||||
|
||||
## Context
|
||||
|
||||
当前项目的执行提示词将 CodeGraph 定位为影响分析的第一层上下文：先用代码关系索引缩小依赖范围，再回到源码、构建配置和精确文本核验，修改共享代码后再检查受影响文件和测试。这个流程既避免在陌生功能区盲目通读，也避免把图谱结果误当成完整事实。
|
||||
|
||||
## Evidence
|
||||
|
||||
- 2026-07-15：用户要求将当前项目的 CodeGraph 使用提示词沉淀到复利工程。
|
||||
- `oppein-react-component/AGENTS.md:23-58`：记录了 CodeGraph 的触发条件、`status`/`sync` 规则、`explore`/`query`/`node`/`impact`/`callers`/`callees`/`affected` 的选择，以及源码核验和常规质量验证边界。
|
||||
- 当前项目存在 `.codegraph/` 本地代码关系索引；该提示词明确要求首次使用时先检查索引状态。
|
||||
|
||||
## Root cause
|
||||
|
||||
已验证：代码关系图适合发现静态依赖、调用方和潜在影响范围，但不能可靠覆盖动态路径、字符串引用、构建配置和实现细节；索引过期时，图谱结论也可能失真。因此图谱只能用于缩小范围，不能单独证明“没有调用方”或“没有影响”。
|
||||
|
||||
推断：把 CodeGraph 放在影响分析前段，并固定接上源码核验与变更后测试范围检查，可以减少漏查共享调用方和遗漏回归测试的风险。
|
||||
|
||||
## Preferred action
|
||||
|
||||
1. 任务首次需要 CodeGraph 时先运行 `codegraph status`；仅在索引不是最新时运行 `codegraph sync`。不要自行执行 `init`、`index` 或 `uninit`，除非用户明确要求，或索引缺失且无法继续完成任务。
|
||||
2. 按问题选择最小工具链：陌生模块用 `codegraph explore "<需求或模块>"`；查定义用 `codegraph query "<符号>"`，再用 `codegraph node "<符号>"` 阅读实现和调用链；修改共享 API 前用 `codegraph impact "<符号>"`，必要时补充 `callers` 和 `callees`。
|
||||
3. 以图谱结果缩小源码阅读和搜索范围；修改前直接阅读相关实现，并用 `rg` 核对动态路径、字符串引用、构建配置和精确文本。
|
||||
4. 共享代码修改完成后运行 `codegraph sync`，再用 `codegraph affected <改动文件>` 找出需要补充或执行的测试，最后仍按项目约定执行 lint、类型检查、构建和针对性测试。
|
||||
|
||||
## Boundaries
|
||||
|
||||
- 只有在项目启用 CodeGraph 且索引或对应 MCP 工具可用时，才直接套用这些命令；其他项目需先确认其工具和命令语义。
|
||||
- 用户已指定文件和行，且只是局部文案、注释、格式或显然不影响外部行为的小改动，以及单文件、无公共接口变化的机械性修复，可以跳过 CodeGraph。
|
||||
- CodeGraph 不能替代源码核验、`rg` 搜索、lint、类型检查、构建或测试；不要仅凭图谱结果断言不存在调用方或影响。
|
||||
|
||||
## Failed approaches
|
||||
|
||||
- 只依据图谱结果判断影响范围，会遗漏动态引用、配置驱动路径和未被索引覆盖的文本关系。
|
||||
- 直接执行 `sync`、`init` 或 `index` 而不先检查状态，会增加不必要的索引操作，并可能偏离项目约定。
|
||||
|
||||
## Promotion record
|
||||
|
||||
- Not promoted. 当前只有 `oppein-react-component` 的一份项目证据；待在另一项目或独立场景复用并验证后，再考虑提升为全局 guidance、skill 或可执行检查。
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
id: 20260724-bounded-list-flex-height-chain
|
||||
title: 有界列表页使用连续 Flex 高度链并收敛滚动视口
|
||||
created: 2026-07-24
|
||||
updated: 2026-07-24
|
||||
status: candidate
|
||||
scope: global
|
||||
category: frontend-layout
|
||||
confidence: medium
|
||||
last_verified: 2026-07-24
|
||||
promotion_target: none
|
||||
projects:
|
||||
- usercenter-react
|
||||
tags:
|
||||
- flex-layout
|
||||
- min-height-zero
|
||||
- bounded-workspace
|
||||
- scroll-ownership
|
||||
- data-table
|
||||
---
|
||||
|
||||
# 有界列表页使用连续 Flex 高度链并收敛滚动视口
|
||||
|
||||
## Trigger
|
||||
|
||||
列表页、主从工作台或树表页面需要填满应用内容区，同时保持标题、筛选、操作栏和分页可见，只让表格数据区、树节点区或详情正文滚动；或者当前页面出现双滚动条、分页被挤出视口、`h-full` 不生效、窗口高度变化后布局失效。
|
||||
|
||||
## Context
|
||||
|
||||
`usercenter-react` 的商场管理页面曾需要移除固定像素高度推算，使应用外壳、路由页面、Tabs、组织树和数据表形成连续的有界高度链。修复后，普通内容页仍由共享 `<main>` 滚动，有界工作台则填满 `<main>` 并把滚动交给最小内容视口。
|
||||
|
||||
这项经验的核心不是“给页面加 `flex-col`”，而是同时解决两个契约：高度从视口向后代连续传递，滚动权从外层收敛到最小内容区域。任一中间层缺少明确高度或 `min-h-0`，后代的 `h-full`、`flex-1` 和 `overflow-auto` 都可能无法按预期工作。
|
||||
|
||||
## Evidence
|
||||
|
||||
- 2026-07-24：重新检查 `usercenter-react` 当前源码、项目规范和 Git 历史；中央经验库搜索“有界列表页 / 连续 Flex 高度链 / min-h-0 / 滚动视口”无重叠条目。
|
||||
- `usercenter-react/src/shared/layout/app-layout.tsx:207-236`：应用根节点使用 `h-dvh overflow-hidden`，内容列使用 `flex h-full min-h-0 flex-col`，共享 `<main>` 使用 `min-h-0 flex-1 overflow-y-auto`。
|
||||
- `usercenter-react/src/features/market-management/pages/market-management-page.tsx:181-230`：有界路由根节点、分栏、Tabs 和 TabPane 连续使用 `h-full`、`flex-1`、`min-h-0` 与受控 overflow。
|
||||
- `usercenter-react/src/shared/table/data-table.tsx:40-45,168-232`：`fillHeight` 以 opt-in 方式把表格面板变成有界 Flex 列，工具栏和分页留在滚动视口之外，数据区域消费剩余高度。
|
||||
- `usercenter-react/.trellis/spec/frontend/layout-guidelines.md:23-32,74-125`：记录了各布局边界的类契约、滚动归属、错误矩阵和禁止使用固定 `calc(100vh - Npx)` 的规则。
|
||||
- `usercenter-react/specs/page-layout.spec.md:5-11`：产品级规范要求有界页面使用连续 Flex 高度链，并将 overflow 委托给最小树或数据视口。
|
||||
- Git 提交 `ccf068c` 修复商场管理页面高度适配，`1bb14e8` 将实践整理为 bounded layout 指南，`849219a` 继续补充可伸缩侧栏场景下的表格滚动与 sticky 边界。
|
||||
- 当前仓库的 `src/shared/list-templates/master-detail-list-template.tsx:34-60` 仍存在 `calc(100vh - 10.5rem)` 实现；这是需要结合响应式父级契约进一步验证的现有反例，不能仅凭规则直接判定或修改。
|
||||
|
||||
## Root cause
|
||||
|
||||
已验证：
|
||||
|
||||
- `flex-col` 和 `flex-1` 只负责空间分配，不会自动建立可解析的高度边界。
|
||||
- Flex/Grid 子项默认的 `min-height: auto` 会阻止内容区域收缩；中间层缺少 `min-h-0` 时，内容会撑高页面而不是在指定视口内滚动。
|
||||
- `h-full` 依赖祖先提供确定高度；高度链中断时，百分比高度不能可靠地代表剩余视口空间。
|
||||
- 页面、共享 `<main>` 和表格数据区同时拥有纵向 overflow 时，会形成嵌套或竞争滚动条。
|
||||
- `calc(100vh - Npx)`、JavaScript 测量和重复的标题高度常量容易在工具栏换行、外壳调整、缩放或窄屏布局下失效。
|
||||
|
||||
推断：把布局评审固定为“先从外向内检查高度链，再从内向外确认唯一滚动所有者”，比逐个添加高度类或 overflow 类更容易定位缺失环节，也更适合跨组件复用。
|
||||
|
||||
## Preferred action
|
||||
|
||||
1. 先区分页面模式：普通内容页继续由应用 `<main>` 滚动；只有需要固定控制区和内部滚动的页面才进入有界模式。
|
||||
2. 从视口向目标滚动区域建立连续高度链：应用根节点建立动态视口边界，中间内容列使用 `flex h-full min-h-0 flex-col`，有界路由根节点使用 `flex h-full min-h-0 flex-col overflow-hidden`。
|
||||
3. 为所有需要消费剩余高度或继续向下传递高度的 Flex/Grid 中间层添加 `min-h-0`；不要只修改最终表格容器。
|
||||
4. 标题、筛选、操作栏、Tabs 头部和分页等固定区域使用 `shrink-0`。剩余内容区域使用 `min-h-0 flex-1`。
|
||||
5. 将纵向滚动交给最小内容视口：通常是表格数据区、树节点区或详情正文。结构层使用 `overflow-hidden`，实际内容视口使用 `overflow-auto` 或 `overflow-y-auto`。
|
||||
6. 共享表格的填高能力保持 opt-in；只有父级已经提供有界 `h-full/min-h-0` 区域时才启用，避免改变普通内容型页面的默认行为。
|
||||
7. 优先使用 Flex 剩余空间，不使用固定 `calc(100vh - Npx)`、JavaScript 高度测量或跨组件共享的像素常量。
|
||||
8. 在真实浏览器中验证滚动归属：有界页面不增加 body 高度，固定控制区和分页保持可见，只有目标数据区滚动；同时检查窄屏、工具栏换行、loading、empty 和 error 状态。类型检查、lint 和构建不能替代这项验证。
|
||||
|
||||
## Examples
|
||||
|
||||
```tsx
|
||||
<div className="h-dvh overflow-hidden">
|
||||
<div className="flex h-full min-h-0 flex-col">
|
||||
<main className="min-h-0 flex-1 overflow-y-auto">
|
||||
<section className="flex h-full min-h-0 flex-col overflow-hidden">
|
||||
<header className="shrink-0">{header}</header>
|
||||
<div className="shrink-0">{filtersAndActions}</div>
|
||||
<div className="min-h-0 flex-1 overflow-hidden">
|
||||
<DataTable fillHeight {...tableProps} />
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
记忆方式：高度从外向内连续传递，滚动权收敛到最小内容视口。
|
||||
|
||||
## Boundaries
|
||||
|
||||
- 普通详情页、表单页和自然增长的长页面通常应继续由共享 `<main>` 滚动，不要为了统一外观强制启用有界模式。
|
||||
- 移动端主从区域改为纵向堆叠时，可能更适合自然页面滚动；有界模式可以只在桌面断点启用。
|
||||
- `overflow-hidden` 只有在后代明确拥有滚动视口时才安全，否则会直接裁切内容。
|
||||
- Tabs、Drawer、Spin、Table 和虚拟列表等第三方组件可能插入包装层，需要根据实际 DOM 补齐高度链或沿用组件自己的滚动机制。
|
||||
- 可交互变宽的分栏可能触发第三方表格的 ResizeObserver 和 sticky 行为；`nativeStickyHeader`、固定列实现等属于组件或项目特例，不是连续 Flex 高度链的通用要求。
|
||||
- 已存在的 `calc(100vh - Npx)` 不应机械替换；需要先确认页面父级是否能提供完整高度链，以及窄屏模式是否依赖自然内容高度。
|
||||
- 当前证据主要来自 `usercenter-react` 的一次完整修复及后续演进。在另一个项目或独立场景复用并完成浏览器验证前，不提升为全局强制规则。
|
||||
|
||||
## Failed approaches
|
||||
|
||||
- 只在页面根节点增加 `flex-col` 或只在表格增加 `flex-1`：高度链仍可能在中间层中断。
|
||||
- 只给最终内容区域增加 `overflow-auto`：默认 `min-height: auto` 仍可能让它撑高父级。
|
||||
- 同时让 `<main>`、路由根节点和表格数据区滚动：容易出现双滚动条、滚轮焦点切换和分页被挤出视口。
|
||||
- 通过 `calc(100vh - Npx)` 或 JavaScript 测量补偿标题高度：在标题、操作栏换行或应用外壳变化后容易产生新的固定偏差。
|
||||
|
||||
## Promotion record
|
||||
|
||||
- Not promoted. 当前已有一个项目中的修复、规范和后续演进证据，先保留为中央 candidate；待第二个项目或独立场景验证后，再考虑提升为 `patterns/` 下的前端布局模式或可执行浏览器检查。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Inbox
|
||||
|
||||
保存刚从任务、用户纠正、失败路径或成功实践中提取的候选经验。
|
||||
|
||||
候选经验尚不能直接视为全局规则。验证后移动到 `learnings/`；没有复用价值的内容直接删除。
|
||||
|
||||
文件命名：`YYYYMMDD-short-slug.md`。
|
||||
@@ -0,0 +1,93 @@
|
||||
# AI Coding 复利大脑
|
||||
|
||||
这里是跨项目 AI coding 经验的统一来源，用于捕获、验证、检索、提升和审计可复用经验。
|
||||
|
||||
## 工作流
|
||||
|
||||
```text
|
||||
项目任务
|
||||
→ inbox 候选经验
|
||||
→ learnings 已验证经验
|
||||
→ patterns 跨项目模式
|
||||
→ assets 可执行资产
|
||||
→ 项目 AGENTS / 测试 / hooks / skills
|
||||
```
|
||||
|
||||
## 导航
|
||||
|
||||
- [[inbox/index|Inbox]]：尚未验证的候选经验
|
||||
- [[learnings/index|Learnings]]：有证据支持的经验
|
||||
- [[patterns/index|Patterns]]：跨项目验证的通用模式
|
||||
- [[projects/index|Projects]]：项目索引和同步状态
|
||||
- [[experiments/index|Experiments]]：模型、提示词和工作流实验
|
||||
- [[assets/index|Assets]]：可以下发的规则、Skill、hook 和 eval
|
||||
- [[maintenance/index|Maintenance]]：冲突、过期和待提升内容
|
||||
|
||||
## 经验 Meta 字段
|
||||
|
||||
每份经验的 YAML frontmatter 使用以下 12 个字段。除特别说明外，字段都应填写；当前 `brain.py validate` 会强制校验前 10 个标量字段，`projects` 和 `tags` 由 schema 约定为必填列表，但暂未被校验脚本强制检查。
|
||||
|
||||
| 字段 | 含义 | 格式或枚举值 |
|
||||
|---|---|---|
|
||||
| `id` | 经验的稳定唯一标识，也用于文件名和检索。 | `YYYYMMDD-short-slug`；日期后接小写字母、数字或连字符，例如 `20260724-bounded-list-flex-height-chain`。 |
|
||||
| `title` | 清晰、可搜索的经验标题，应概括触发场景和核心做法。 | 自由文本，无固定枚举。 |
|
||||
| `created` | 首次创建该经验的日期。 | `YYYY-MM-DD`。 |
|
||||
| `updated` | 最近一次实质更新该经验内容或元信息的日期。 | `YYYY-MM-DD`。 |
|
||||
| `status` | 经验在验证与提升生命周期中的状态。 | `candidate`、`validated`、`promoted`、`stale`、`superseded`。 |
|
||||
| `scope` | 经验适用范围的最小边界。 | `global`、`repository`、`module`。 |
|
||||
| `category` | 用于按问题域或实践类型归类和检索。 | 自由的 kebab-case 分类，无固定枚举；当前已有 `agent-workflows`、`debugging`、`frontend-layout`。 |
|
||||
| `confidence` | 基于现有证据，对经验可靠程度的判断。 | `low`、`medium`、`high`。 |
|
||||
| `last_verified` | 最近一次用当前代码、运行结果、文档或其他证据核验该经验的日期；只有实际复核后才更新。 | `YYYY-MM-DD`。 |
|
||||
| `promotion_target` | 该经验已经提升到或计划提升到的最小持久化执行载体；尚无目标时填 `none`。 | `none`、`global-agents`、`repo-agents`、`skill`、`test`、`lint`、`hook`、`script`、`docs`、`pattern`、`eval`。 |
|
||||
| `projects` | 产生、验证或适用过该经验的项目，用于追溯证据与判断是否跨项目成立。 | YAML 字符串列表，无固定枚举；使用稳定的项目名。 |
|
||||
| `tags` | 更细粒度的检索关键词，描述技术、组件、故障模式或工作流。 | YAML 字符串列表，无固定枚举；建议使用简短的 kebab-case 标签。 |
|
||||
|
||||
### `status` 枚举含义
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `candidate` | 刚捕获的候选经验，已有复用信号，但证据还不足以作为稳定规则。 |
|
||||
| `validated` | 已有当前、可检查的证据支持，适用边界也已确认。 |
|
||||
| `promoted` | 已写入并验证某个持久化载体；具体载体记录在 `promotion_target` 和 `Promotion record` 中。 |
|
||||
| `stale` | 当前真实性不确定，或已被新代码、证据、文档或执行载体否定；不能直接复用。 |
|
||||
| `superseded` | 已由更新、更完整的规范经验替代；应指向替代项，避免继续作为主来源。 |
|
||||
|
||||
### `scope` 枚举含义
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `global` | 跨仓库、跨项目通常成立，但复用前仍需核对当前上下文。 |
|
||||
| `repository` | 只对某个仓库的命令、架构、约定或运行环境成立。 |
|
||||
| `module` | 只对仓库内某个模块、组件或局部边界成立。 |
|
||||
|
||||
### `confidence` 枚举含义
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `low` | 主要是初步观察或推断，证据有限，复用前需要重点验证。 |
|
||||
| `medium` | 有明确实例或验证结果支持，但复现次数、覆盖范围或边界仍有限。 |
|
||||
| `high` | 有强且可复查的证据，通常经过独立复现、跨项目验证，或有高严重度事件及已验证的预防机制。 |
|
||||
|
||||
### `promotion_target` 枚举含义
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `none` | 尚未决定或不需要提升到其他载体。 |
|
||||
| `global-agents` | 跨仓库稳定适用的个人全局 Agent 指引。 |
|
||||
| `repo-agents` | 特定仓库的 `AGENTS.md` 规则或约定。 |
|
||||
| `skill` | 有清晰触发条件、输入、输出和验证方式的可复用多步工作流。 |
|
||||
| `test` | 用自动化测试守护可确定验证的行为或不变量。 |
|
||||
| `lint` | 用静态检查规则发现可机械识别的问题。 |
|
||||
| `hook` | 在提交、推送或其他生命周期节点自动执行的检查或动作。 |
|
||||
| `script` | 用可重复运行的脚本固化操作、检查或修复流程。 |
|
||||
| `docs` | 与项目代码或运行方式绑定的解释性文档。 |
|
||||
| `pattern` | 至少经过两次独立验证的跨项目工程原则或规范模式。 |
|
||||
| `eval` | 针对可复现的 Agent 行为回归建立评测用例和可观察的通过标准。 |
|
||||
|
||||
## 原则
|
||||
|
||||
- 笔记数量不是指标，行为改善才是。
|
||||
- 项目事实留在项目中；这里保存索引、证据和跨项目归纳。
|
||||
- 先搜索再读取，避免把整个知识库注入上下文。
|
||||
- 能用测试、lint、hook 或脚本执行的规则，不只保留为文字。
|
||||
- 所有经验都要说明边界和最后验证日期。
|
||||
@@ -0,0 +1,14 @@
|
||||
# Learnings
|
||||
|
||||
保存已有明确证据、适用边界和首选行动的经验。
|
||||
|
||||
按实际增长情况建立主题目录，例如：
|
||||
|
||||
- debugging
|
||||
- planning
|
||||
- testing
|
||||
- review
|
||||
- context-engineering
|
||||
- agent-workflows
|
||||
|
||||
不要预先创建空分类。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Conflicts
|
||||
|
||||
当前没有待处理冲突。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Maintenance
|
||||
|
||||
- [[conflicts]]：互相冲突、需要进一步验证的经验
|
||||
- [[promotion-queue]]：已满足证据条件、等待提升的经验
|
||||
- [[stale]]：当前真实性不足或执行资产已经漂移的经验
|
||||
|
||||
年龄本身不是过期证据。应根据代码、工具、文档和实际行为判断。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Promotion Queue
|
||||
|
||||
当前没有等待提升的经验。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Stale
|
||||
|
||||
当前没有标记为 stale 的经验。
|
||||
@@ -0,0 +1,11 @@
|
||||
# Patterns
|
||||
|
||||
保存至少经过两个独立项目或场景验证的跨项目模式。
|
||||
|
||||
Pattern 应说明：
|
||||
|
||||
- 触发条件
|
||||
- 核心机制
|
||||
- 适用与不适用边界
|
||||
- 支撑它的 learning
|
||||
- 已提升到哪些执行资产
|
||||
@@ -0,0 +1,11 @@
|
||||
# Projects
|
||||
|
||||
为每个项目维护一份简短索引，记录：
|
||||
|
||||
- 仓库位置
|
||||
- 项目内知识入口
|
||||
- 已贡献到公共仓库的经验
|
||||
- 从公共仓库同步回项目的规则或资产
|
||||
- 最后审计日期
|
||||
|
||||
项目专属事实和强制规则仍以项目仓库为准。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: ARTIFACT-MODEL-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 产物模型
|
||||
|
||||
## 基本原则
|
||||
|
||||
每个需求产物都是一个可追踪 artifact。目录结构用于人工导航，frontmatter 用于机器读取和关联。
|
||||
|
||||
## 通用 frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: UR-20260629-001
|
||||
case_id: REQ-20260629-001
|
||||
type: user-requirement
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- INTAKE-20260629-001
|
||||
derived_ids:
|
||||
- RA-20260629-001
|
||||
- SA-20260629-001
|
||||
skill:
|
||||
name: pm-requirement-refine
|
||||
version: 0.1.0
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
```
|
||||
|
||||
## 产物类型
|
||||
|
||||
| type | 阶段 | 负责人 | 主要输入 | 主要输出 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| intake | 用户需求 | PM | 原始输入 | 需求背景、目标、问题陈述 |
|
||||
| user-requirement | 用户需求 | PM | intake | UR |
|
||||
| requirement-analysis | 用户需求 | PM | UR | RA |
|
||||
| scenario-analysis | 用户需求 | PM | UR / RA | SA |
|
||||
| objective-requirement | 研发需求 | SE | UR / RA / SA | OR |
|
||||
| development-requirement | 研发需求 | SE | OR | DR |
|
||||
| design-specification | 详细设计 | RD | OR / DR | DS |
|
||||
| implementation-task | 编码 | RD / AI | DS | 开发任务、变更集 |
|
||||
| test-plan | 测试 | QA / RD / AI | UR / OR / DR / DS | TP |
|
||||
| test-case | 测试 | QA / RD / AI | TP / DS | TC |
|
||||
|
||||
## 状态
|
||||
|
||||
- `draft`：草稿。
|
||||
- `reviewing`：评审中。
|
||||
- `approved`：已通过评审。
|
||||
- `rework`：需要返工。
|
||||
- `implemented`：已实现。
|
||||
- `verified`：已验证。
|
||||
- `archived`：已归档。
|
||||
|
||||
## 关联方向
|
||||
|
||||
- `source_ids`：当前产物直接依赖的上游产物。
|
||||
- `derived_ids`：由当前产物直接产出的下游产物。
|
||||
- `case_id`：将同一需求链路下的所有产物绑定到一个需求实例。
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: GLOSSARY-AI-RD-WORKFLOW
|
||||
type: glossary
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 术语
|
||||
|
||||
| 缩写 | 名称 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| INTAKE | 原始输入 | 用户、业务方、运营、客户等给出的初始需求输入。 |
|
||||
| UR | User Requirement | 用户需求。描述用户目标、业务价值、范围和验收方向。 |
|
||||
| RA | Requirement Analysis | 需求分析。对用户需求进行澄清、拆解、约束识别和风险分析。 |
|
||||
| SA | Scenario Analysis | 场景分析。描述典型用户场景、异常场景、边界场景。 |
|
||||
| OR | Objective Requirement | 研发目标需求。由 SE 从业务目标转译为研发目标、范围、成功标准和约束。 |
|
||||
| DR | Development Requirement | 研发需求。描述功能、非功能、接口、数据、依赖、兼容性等工程要求。 |
|
||||
| DS | Design Specification | 详细设计。RD 基于 OR、DR 输出的可开发设计说明。 |
|
||||
| TP | Test Plan | 测试计划。描述测试范围、策略、环境和准入准出条件。 |
|
||||
| TC | Test Case | 测试用例。描述具体测试步骤、数据、预期结果和关联需求。 |
|
||||
| Traceability | 追踪关系 | 任一产物与上游输入、下游产物之间的可查关系。 |
|
||||
|
||||
> 这些缩写是本工作区的初始约定，可以在后续迭代中重命名，但要同步更新模板、skill 和示例 case。
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: NAMING-CONVENTIONS-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 命名规范
|
||||
|
||||
## Case ID
|
||||
|
||||
格式：
|
||||
|
||||
```text
|
||||
REQ-yyyymmdd-nnn-short-name
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
REQ-20260629-001-ai-rd-workflow
|
||||
```
|
||||
|
||||
## Artifact ID
|
||||
|
||||
格式：
|
||||
|
||||
```text
|
||||
<PREFIX>-yyyymmdd-nnn
|
||||
```
|
||||
|
||||
常用前缀：
|
||||
|
||||
- `INTAKE`
|
||||
- `UR`
|
||||
- `RA`
|
||||
- `SA`
|
||||
- `OR`
|
||||
- `DR`
|
||||
- `DS`
|
||||
- `TASK`
|
||||
- `TP`
|
||||
- `TC`
|
||||
|
||||
## 文件名
|
||||
|
||||
真实 case 中推荐使用：
|
||||
|
||||
```text
|
||||
<ARTIFACT-ID>-<short-name>.md
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
UR-20260629-001-ai-rd-workflow.md
|
||||
```
|
||||
|
||||
模板文件使用语义名称：
|
||||
|
||||
```text
|
||||
user-requirement.md
|
||||
scenario-analysis.md
|
||||
design-specification.md
|
||||
```
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
id: ROADMAP-AI-RD-WORKFLOW
|
||||
type: roadmap
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 路线图
|
||||
|
||||
## M0：骨架期
|
||||
|
||||
- 建立目录结构、文档类型、ID 规则和追踪关系。
|
||||
- 创建第一批模板和 skill 草稿。
|
||||
- 用一个示例 case 跑通链路。
|
||||
|
||||
## M1：PM 需求侧
|
||||
|
||||
- 完善用户需求评审 skill。
|
||||
- 完善需求细化 skill。
|
||||
- 固化需求分析、场景分析、验收标准模板。
|
||||
|
||||
## M2：SE 研发需求侧
|
||||
|
||||
- 完善研发需求评审 skill。
|
||||
- 明确 OR、DR 的字段、质量标准和评审门禁。
|
||||
- 建立从 PM 产物到 SE 产物的追踪矩阵。
|
||||
|
||||
## M3：RD 详细设计侧
|
||||
|
||||
- 完善从 OR、DR 生成 DS 的 skill。
|
||||
- 将 DS 拆到可由 AI 执行的开发任务粒度。
|
||||
- 明确接口、数据、状态、异常、测试点的设计要求。
|
||||
|
||||
## M4：编码与测试闭环
|
||||
|
||||
- 建立 AI 编码任务模板。
|
||||
- 建立测试计划和测试用例生成 skill。
|
||||
- 建立变更影响分析和回归范围识别规则。
|
||||
|
||||
## M5：评测与持续优化
|
||||
|
||||
- 建立 skill eval case。
|
||||
- 记录 prompt run 与失败样本。
|
||||
- 通过复盘更新规范、模板和 skill。
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: LIFECYCLE-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 生命周期
|
||||
|
||||
## 1. 用户需求
|
||||
|
||||
负责人：PM
|
||||
|
||||
输入：原始用户需求、业务背景、访谈记录、问题描述。
|
||||
|
||||
输出：
|
||||
|
||||
- UR：用户需求。
|
||||
- RA：需求分析。
|
||||
- SA：场景分析。
|
||||
|
||||
关键动作：
|
||||
|
||||
- 评审原始需求是否清晰、完整、有价值。
|
||||
- 细化用户目标、业务价值、成功标准。
|
||||
- 补齐主场景、异常场景、边界场景。
|
||||
|
||||
## 2. 研发需求
|
||||
|
||||
负责人：SE
|
||||
|
||||
输入：UR、RA、SA。
|
||||
|
||||
输出：
|
||||
|
||||
- OR：研发目标需求。
|
||||
- DR：研发需求。
|
||||
|
||||
关键动作：
|
||||
|
||||
- 将业务目标转译为工程目标。
|
||||
- 明确功能范围、非功能要求、接口、数据、依赖和约束。
|
||||
- 识别技术风险、拆分边界和交付策略。
|
||||
|
||||
## 3. 详细设计
|
||||
|
||||
负责人：RD
|
||||
|
||||
输入：OR、DR。
|
||||
|
||||
输出：
|
||||
|
||||
- DS：详细设计。
|
||||
- TASK：可开发任务。
|
||||
|
||||
关键动作：
|
||||
|
||||
- 拆分模块、接口、数据结构、状态流和异常处理。
|
||||
- 将设计落到可由 AI 或研发执行的任务粒度。
|
||||
- 标注测试点、兼容性和回归影响。
|
||||
|
||||
## 4. 编码
|
||||
|
||||
负责人：RD / AI agent
|
||||
|
||||
输入：DS、TASK。
|
||||
|
||||
输出：代码变更、实现说明、风险说明。
|
||||
|
||||
关键动作：
|
||||
|
||||
- 按任务边界实现。
|
||||
- 维护变更与 DS、DR 的映射。
|
||||
- 运行必要验证。
|
||||
|
||||
## 5. 测试
|
||||
|
||||
负责人：QA / RD / AI agent
|
||||
|
||||
输入：UR、OR、DR、DS、代码变更。
|
||||
|
||||
输出：
|
||||
|
||||
- TP：测试计划。
|
||||
- TC：测试用例。
|
||||
- 测试结果。
|
||||
|
||||
关键动作：
|
||||
|
||||
- 从需求和设计生成测试覆盖。
|
||||
- 标记正向、异常、边界、回归用例。
|
||||
- 记录未覆盖风险。
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: REVIEW-GATES-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 评审门禁
|
||||
|
||||
## Gate 1：用户需求评审
|
||||
|
||||
通过条件：
|
||||
|
||||
- 目标用户和核心问题明确。
|
||||
- 业务价值和优先级明确。
|
||||
- 需求范围与非目标明确。
|
||||
- 关键场景、异常场景、边界场景已覆盖。
|
||||
- 验收方向可被验证。
|
||||
|
||||
## Gate 2：研发需求评审
|
||||
|
||||
通过条件：
|
||||
|
||||
- OR 能追溯到 UR、RA、SA。
|
||||
- DR 覆盖功能、非功能、接口、数据、依赖、约束。
|
||||
- 关键风险和未知项已标记 owner。
|
||||
- 拆分策略适合后续详细设计。
|
||||
|
||||
## Gate 3：详细设计评审
|
||||
|
||||
通过条件：
|
||||
|
||||
- DS 能追溯到 OR、DR。
|
||||
- 模块、接口、数据、状态、异常处理清晰。
|
||||
- 每个开发任务边界清晰且可独立验证。
|
||||
- 测试点和回归影响已标注。
|
||||
|
||||
## Gate 4：编码准出
|
||||
|
||||
通过条件：
|
||||
|
||||
- 代码变更能追溯到 DS/TASK。
|
||||
- 本地验证通过或说明未验证原因。
|
||||
- 变更影响范围明确。
|
||||
- 未完成项和技术债已记录。
|
||||
|
||||
## Gate 5：测试准出
|
||||
|
||||
通过条件：
|
||||
|
||||
- 测试用例覆盖 UR、OR、DR、DS 的关键点。
|
||||
- 失败用例有明确处理结论。
|
||||
- 未覆盖风险已记录。
|
||||
- 需求链路状态可更新为 `verified` 或 `rework`。
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: ROLES-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 角色边界
|
||||
|
||||
## PM
|
||||
|
||||
负责用户需求侧产物：
|
||||
|
||||
- 收集原始输入。
|
||||
- 评审和澄清用户需求。
|
||||
- 产出 UR、RA、SA。
|
||||
- 维护业务价值、优先级和验收方向。
|
||||
|
||||
## SE
|
||||
|
||||
负责研发需求侧产物：
|
||||
|
||||
- 评审 PM 产物的工程可转译性。
|
||||
- 产出 OR、DR。
|
||||
- 识别技术依赖、集成边界、非功能要求和风险。
|
||||
- 推动需求进入详细设计。
|
||||
|
||||
## RD
|
||||
|
||||
负责详细设计和实现：
|
||||
|
||||
- 基于 OR、DR 产出 DS。
|
||||
- 将 DS 拆为 TASK。
|
||||
- 使用 AI agent 或人工完成编码。
|
||||
- 维护实现与设计之间的追踪关系。
|
||||
|
||||
## QA
|
||||
|
||||
负责测试设计和验证：
|
||||
|
||||
- 基于 UR、OR、DR、DS 设计 TP、TC。
|
||||
- 维护覆盖关系和测试结果。
|
||||
- 标记质量风险和回归范围。
|
||||
|
||||
## AI Agent
|
||||
|
||||
作为执行与分析助手：
|
||||
|
||||
- 执行 skill 中定义的流程。
|
||||
- 生成或补全阶段产物。
|
||||
- 检查追踪关系。
|
||||
- 根据 DS/TASK 编码并验证。
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
id: TRACEABILITY-AI-RD-WORKFLOW
|
||||
type: standard
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 追踪规则
|
||||
|
||||
## 基本规则
|
||||
|
||||
1. 每个 artifact 必须有唯一 `id`。
|
||||
2. 每个真实需求必须有统一 `case_id`。
|
||||
3. 下游产物必须在 `source_ids` 中声明直接上游。
|
||||
4. 上游产物应在 `derived_ids` 中声明直接下游。
|
||||
5. 如果需求变更影响已通过评审的产物，必须新增变更记录或更新状态为 `rework`。
|
||||
|
||||
## 推荐链路
|
||||
|
||||
```text
|
||||
INTAKE
|
||||
-> UR
|
||||
-> RA
|
||||
-> SA
|
||||
-> OR
|
||||
-> DR
|
||||
-> DS
|
||||
-> TASK
|
||||
-> TP
|
||||
-> TC
|
||||
```
|
||||
|
||||
实际项目允许分支，例如一个 DR 产生多个 DS，一个 DS 产生多个 TASK。
|
||||
|
||||
## 追踪矩阵字段
|
||||
|
||||
在每个 case 的 `traceability.md` 中维护：
|
||||
|
||||
| 上游 ID | 下游 ID | 关系 | 覆盖状态 | 备注 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| UR-xxx | OR-xxx | derives | covered | - |
|
||||
|
||||
覆盖状态：
|
||||
|
||||
- `covered`：已覆盖。
|
||||
- `partial`：部分覆盖。
|
||||
- `missing`：缺失。
|
||||
- `changed`：上游变更后待更新。
|
||||
- `not-applicable`：明确不适用。
|
||||
|
||||
## AI 检查点
|
||||
|
||||
每次进入下一阶段前，让 AI agent 检查：
|
||||
|
||||
- 是否存在没有下游的关键上游产物。
|
||||
- 是否存在没有上游的下游产物。
|
||||
- 是否存在 status 不一致的产物。
|
||||
- 是否存在已变更但未重新评审的产物。
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
id: SKILLS-INDEX-AI-RD-WORKFLOW
|
||||
type: skills-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# Skill 草稿
|
||||
|
||||
这里维护的是 skill 源草稿，用于长期打磨。稳定后再复制或安装到 `$CODEX_HOME/skills` 或 `~/.codex/skills`，让 Codex 自动发现。
|
||||
|
||||
## 当前 skill
|
||||
|
||||
- `pm-requirement-review`：PM 用户需求评审。
|
||||
- `pm-requirement-refine`：PM 用户需求细化。
|
||||
- `se-requirement-review`：SE 研发需求评审。
|
||||
- `se-requirement-analysis`：SE 研发需求分析。
|
||||
- `rd-design-generate`：RD 详细设计生成。
|
||||
- `test-case-generate`：测试计划和测试用例生成。
|
||||
|
||||
## 调优方式
|
||||
|
||||
1. 选择一个真实 case。
|
||||
2. 使用对应 skill 生成产物。
|
||||
3. 将失败点记录到 `60-evaluations/retrospectives/`。
|
||||
4. 更新 skill、模板或规范。
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: pm-requirement-refine
|
||||
description: Refine user-facing requirements from a PM perspective. Use when Codex needs to transform reviewed intake into traceable user requirement, requirement analysis, scenario analysis, user stories, acceptance criteria, and open questions.
|
||||
---
|
||||
|
||||
# PM Requirement Refine
|
||||
|
||||
Refine a reviewed intake into PM-side requirement artifacts.
|
||||
|
||||
## Inputs
|
||||
|
||||
- INTAKE.
|
||||
- PM review note.
|
||||
- Existing business context.
|
||||
|
||||
## Process
|
||||
|
||||
1. Write the user requirement in user-goal language.
|
||||
2. Extract business value, target users, constraints, and non-goals.
|
||||
3. Produce requirement analysis with assumptions, dependencies, and risks.
|
||||
4. Produce scenario analysis for main, alternative, exception, and boundary scenarios.
|
||||
5. Define acceptance criteria that can be verified later.
|
||||
6. Create traceability metadata for all generated artifacts.
|
||||
|
||||
## Output
|
||||
|
||||
Generate or update:
|
||||
|
||||
- UR.
|
||||
- RA.
|
||||
- SA.
|
||||
- Open question list.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
- Each requirement has a clear user or business value.
|
||||
- Each scenario maps to at least one requirement.
|
||||
- Each acceptance criterion is observable.
|
||||
- Unknowns are not hidden inside polished prose.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: pm-requirement-review
|
||||
description: Review raw user or business requirements from a PM perspective. Use when Codex needs to assess whether an intake or user requirement is clear, valuable, scoped, testable, and ready for refinement into requirement analysis and scenario analysis.
|
||||
---
|
||||
|
||||
# PM Requirement Review
|
||||
|
||||
Review the input as a PM before refinement.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Intake document or raw user request.
|
||||
- Existing UR, RA, or SA if available.
|
||||
|
||||
## Process
|
||||
|
||||
1. Identify the target user, business goal, and triggering problem.
|
||||
2. Check whether the requested outcome is measurable.
|
||||
3. Separate in-scope, out-of-scope, and unknown items.
|
||||
4. Identify missing context, ambiguous terms, hidden assumptions, and decision points.
|
||||
5. Check whether acceptance direction can be verified.
|
||||
|
||||
## Output
|
||||
|
||||
Produce a review note with:
|
||||
|
||||
- Summary.
|
||||
- Confirmed facts.
|
||||
- Ambiguities.
|
||||
- Missing information.
|
||||
- Scope risks.
|
||||
- Scenario gaps.
|
||||
- Recommended next questions.
|
||||
- Gate decision: `pass`, `pass-with-questions`, or `rework`.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not invent business facts.
|
||||
- Mark assumptions explicitly.
|
||||
- Prefer concrete questions over broad advice.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: rd-design-generate
|
||||
description: Generate detailed design specifications from SE-produced OR and DR. Use when Codex needs to help an RD decompose engineering requirements into modules, APIs, data changes, state flows, error handling, implementation tasks, and test points for AI-assisted development.
|
||||
---
|
||||
|
||||
# RD Design Generate
|
||||
|
||||
Generate detailed design from OR and DR.
|
||||
|
||||
## Inputs
|
||||
|
||||
- OR.
|
||||
- DR.
|
||||
- Existing architecture or code context if available.
|
||||
|
||||
## Process
|
||||
|
||||
1. Identify affected modules and boundaries.
|
||||
2. Define proposed design, alternatives considered, and tradeoffs.
|
||||
3. Specify API, data model, state flow, permissions, error handling, observability, and compatibility changes.
|
||||
4. Split the design into implementation tasks.
|
||||
5. Add test points and regression impact.
|
||||
6. Preserve traceability from DS and TASK back to OR/DR.
|
||||
|
||||
## Output
|
||||
|
||||
Generate:
|
||||
|
||||
- DS.
|
||||
- TASK list.
|
||||
- Test point list.
|
||||
- Open technical questions.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
- A developer or AI agent can implement each task without reinterpreting business intent.
|
||||
- Risky areas are marked explicitly.
|
||||
- Test points are connected to design decisions.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: se-requirement-analysis
|
||||
description: Create engineering-side objective requirements and development requirements from PM-side artifacts. Use when Codex needs to transform UR, requirement analysis, and scenario analysis into OR and DR with traceable functional, non-functional, interface, data, dependency, and risk requirements.
|
||||
---
|
||||
|
||||
# SE Requirement Analysis
|
||||
|
||||
Transform PM artifacts into engineering requirements.
|
||||
|
||||
## Inputs
|
||||
|
||||
- UR.
|
||||
- RA.
|
||||
- SA.
|
||||
- SE review note.
|
||||
|
||||
## Process
|
||||
|
||||
1. Create OR with engineering objective, delivery scope, success metrics, and constraints.
|
||||
2. Create DR with functional requirements, non-functional requirements, API/interface requirements, data requirements, dependencies, compatibility, rollout, and observability.
|
||||
3. Map each OR/DR item back to source IDs.
|
||||
4. Mark open questions and assumptions.
|
||||
5. Identify DS candidates for RD breakdown.
|
||||
|
||||
## Output
|
||||
|
||||
Generate:
|
||||
|
||||
- OR.
|
||||
- DR.
|
||||
- Traceability updates.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
- Every critical UR has engineering coverage or an explicit exclusion.
|
||||
- DR items are specific enough for detailed design.
|
||||
- Risks and unknowns are visible.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: se-requirement-review
|
||||
description: Review PM-side requirement artifacts from an SE perspective. Use when Codex needs to evaluate whether UR, requirement analysis, and scenario analysis are ready to become engineering objective requirements and development requirements.
|
||||
---
|
||||
|
||||
# SE Requirement Review
|
||||
|
||||
Review PM artifacts for engineering readiness.
|
||||
|
||||
## Inputs
|
||||
|
||||
- UR.
|
||||
- RA.
|
||||
- SA.
|
||||
- PM open questions and review notes.
|
||||
|
||||
## Process
|
||||
|
||||
1. Check whether business requirements can be translated into engineering outcomes.
|
||||
2. Identify missing non-functional requirements.
|
||||
3. Identify interface, data, dependency, integration, permission, migration, and compatibility concerns.
|
||||
4. Identify architectural or delivery risks.
|
||||
5. Mark unresolved questions that block OR or DR.
|
||||
|
||||
## Output
|
||||
|
||||
Produce an SE review note with:
|
||||
|
||||
- Engineering readiness decision.
|
||||
- Blocking questions.
|
||||
- Required technical clarifications.
|
||||
- Risk list.
|
||||
- Suggested OR/DR breakdown.
|
||||
|
||||
## Decision
|
||||
|
||||
Use one of:
|
||||
|
||||
- `ready-for-or-dr`
|
||||
- `ready-with-risks`
|
||||
- `blocked`
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: test-case-generate
|
||||
description: Generate test plans and test cases from user requirements, engineering requirements, detailed design, and implementation tasks. Use when Codex needs to produce traceable positive, negative, boundary, regression, and risk-based tests.
|
||||
---
|
||||
|
||||
# Test Case Generate
|
||||
|
||||
Generate test artifacts from requirements and design.
|
||||
|
||||
## Inputs
|
||||
|
||||
- UR, RA, SA.
|
||||
- OR, DR.
|
||||
- DS and TASK.
|
||||
- Existing test conventions if available.
|
||||
|
||||
## Process
|
||||
|
||||
1. Identify test scope and non-scope.
|
||||
2. Build a test plan with strategy, environment, data, entry criteria, and exit criteria.
|
||||
3. Generate test cases for main, exception, boundary, permission, compatibility, and regression paths.
|
||||
4. Map each test case to source requirement or design IDs.
|
||||
5. Mark untestable or unclear requirements.
|
||||
|
||||
## Output
|
||||
|
||||
Generate:
|
||||
|
||||
- TP.
|
||||
- TC list.
|
||||
- Coverage gaps.
|
||||
- Risk-based regression suggestions.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
- Each critical requirement has coverage.
|
||||
- Expected results are concrete.
|
||||
- Test data and preconditions are explicit.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
id: DR-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: development-requirement
|
||||
stage: development-requirement
|
||||
owner_role: SE
|
||||
status: draft
|
||||
source_ids:
|
||||
- OR-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: se-requirement-analysis
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# DR：研发需求
|
||||
|
||||
## 功能需求
|
||||
|
||||
## 非功能需求
|
||||
|
||||
## 接口需求
|
||||
|
||||
## 数据需求
|
||||
|
||||
## 权限与安全
|
||||
|
||||
## 兼容性
|
||||
|
||||
## 依赖
|
||||
|
||||
## 观测与日志
|
||||
|
||||
## 发布与回滚
|
||||
|
||||
## 来源映射
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: DS-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: design-specification
|
||||
stage: detailed-design
|
||||
owner_role: RD
|
||||
status: draft
|
||||
source_ids:
|
||||
- OR-yyyymmdd-nnn
|
||||
- DR-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: rd-design-generate
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# DS：详细设计
|
||||
|
||||
## 背景
|
||||
|
||||
## 影响范围
|
||||
|
||||
## 模块拆分
|
||||
|
||||
## 接口设计
|
||||
|
||||
## 数据设计
|
||||
|
||||
## 状态流
|
||||
|
||||
## 异常处理
|
||||
|
||||
## 权限与安全
|
||||
|
||||
## 兼容性与迁移
|
||||
|
||||
## 观测与日志
|
||||
|
||||
## 开发任务拆分
|
||||
|
||||
## 测试点
|
||||
|
||||
## 风险与待确认
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
id: INTAKE-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: intake
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids: []
|
||||
derived_ids: []
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 原始输入
|
||||
|
||||
## 背景
|
||||
|
||||
## 原始描述
|
||||
|
||||
## 目标用户
|
||||
|
||||
## 当前问题
|
||||
|
||||
## 期望结果
|
||||
|
||||
## 约束
|
||||
|
||||
## 已知材料
|
||||
|
||||
## 待确认问题
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: OR-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: objective-requirement
|
||||
stage: development-requirement
|
||||
owner_role: SE
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-yyyymmdd-nnn
|
||||
- RA-yyyymmdd-nnn
|
||||
- SA-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: se-requirement-analysis
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# OR：研发目标需求
|
||||
|
||||
## 工程目标
|
||||
|
||||
## 交付范围
|
||||
|
||||
## 成功标准
|
||||
|
||||
## 约束
|
||||
|
||||
## 非目标
|
||||
|
||||
## 风险
|
||||
|
||||
## 来源映射
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
id: RA-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: requirement-analysis
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: pm-requirement-refine
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 需求分析
|
||||
|
||||
## 问题拆解
|
||||
|
||||
## 用户/业务价值
|
||||
|
||||
## 功能需求
|
||||
|
||||
## 非功能关注点
|
||||
|
||||
## 约束
|
||||
|
||||
## 依赖
|
||||
|
||||
## 风险
|
||||
|
||||
## 决策点
|
||||
|
||||
## 待确认问题
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
id: SA-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: scenario-analysis
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-yyyymmdd-nnn
|
||||
- RA-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: pm-requirement-refine
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 场景分析
|
||||
|
||||
## 主场景
|
||||
|
||||
## 替代场景
|
||||
|
||||
## 异常场景
|
||||
|
||||
## 边界场景
|
||||
|
||||
## 角色与权限
|
||||
|
||||
## 数据变化
|
||||
|
||||
## 验收标准映射
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
id: TC-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: test-case
|
||||
stage: test
|
||||
owner_role: QA
|
||||
status: draft
|
||||
source_ids:
|
||||
- TP-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: test-case-generate
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 测试用例
|
||||
|
||||
| 用例 ID | 类型 | 来源 ID | 前置条件 | 步骤 | 预期结果 | 优先级 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| TC-yyyymmdd-001 | positive | DR-yyyymmdd-nnn | | | | P0 |
|
||||
|
||||
## 覆盖缺口
|
||||
|
||||
## 风险说明
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: TP-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: test-plan
|
||||
stage: test
|
||||
owner_role: QA
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-yyyymmdd-nnn
|
||||
- OR-yyyymmdd-nnn
|
||||
- DR-yyyymmdd-nnn
|
||||
- DS-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: test-case-generate
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 测试计划
|
||||
|
||||
## 测试范围
|
||||
|
||||
## 非测试范围
|
||||
|
||||
## 测试策略
|
||||
|
||||
## 测试环境
|
||||
|
||||
## 测试数据
|
||||
|
||||
## 准入条件
|
||||
|
||||
## 准出条件
|
||||
|
||||
## 风险
|
||||
|
||||
## 覆盖矩阵
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
id: UR-yyyymmdd-nnn
|
||||
case_id: REQ-yyyymmdd-nnn-short-name
|
||||
type: user-requirement
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- INTAKE-yyyymmdd-nnn
|
||||
derived_ids: []
|
||||
skill:
|
||||
name: pm-requirement-refine
|
||||
version: 0.1.0
|
||||
created: yyyy-mm-dd
|
||||
updated: yyyy-mm-dd
|
||||
---
|
||||
|
||||
# 用户需求
|
||||
|
||||
## 一句话需求
|
||||
|
||||
## 用户目标
|
||||
|
||||
## 业务价值
|
||||
|
||||
## 范围
|
||||
|
||||
### 包含
|
||||
|
||||
### 不包含
|
||||
|
||||
## 验收方向
|
||||
|
||||
## 优先级
|
||||
|
||||
## 假设
|
||||
|
||||
## 待确认问题
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: AI-DEVELOPMENT-WORKFLOW
|
||||
type: workflow
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# AI 开发工作流
|
||||
|
||||
## 输入
|
||||
|
||||
- 已通过评审的 DS。
|
||||
- 明确的 TASK。
|
||||
- 当前代码库上下文。
|
||||
- 测试命令和验收方式。
|
||||
|
||||
## 执行
|
||||
|
||||
1. 读取 TASK 和相关 DS。
|
||||
2. 定位受影响代码。
|
||||
3. 给出实现计划。
|
||||
4. 修改代码。
|
||||
5. 运行验证。
|
||||
6. 更新任务状态和风险说明。
|
||||
|
||||
## 输出
|
||||
|
||||
- 代码变更摘要。
|
||||
- 验证结果。
|
||||
- 未完成项。
|
||||
- 与需求 ID 的映射。
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: PM-WORKFLOW-AI-RD
|
||||
type: workflow
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# PM 工作流
|
||||
|
||||
1. 收集原始输入，创建 INTAKE。
|
||||
2. 使用 `pm-requirement-review` 评审需求。
|
||||
3. 补齐问题后，使用 `pm-requirement-refine` 生成 UR、RA、SA。
|
||||
4. 更新 case 的 `traceability.md`。
|
||||
5. 进入 Gate 1 用户需求评审。
|
||||
6. 评审通过后交给 SE。
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: RD-WORKFLOW-AI-RD
|
||||
type: workflow
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# RD 工作流
|
||||
|
||||
1. 接收 SE 侧 OR、DR。
|
||||
2. 使用 `rd-design-generate` 生成 DS。
|
||||
3. 将 DS 拆为 TASK。
|
||||
4. 明确每个 TASK 的输入、输出、文件范围、测试点。
|
||||
5. 使用 AI agent 或人工编码。
|
||||
6. 将代码变更关联回 TASK/DS。
|
||||
7. 进入 Gate 3 和 Gate 4。
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: SE-WORKFLOW-AI-RD
|
||||
type: workflow
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# SE 工作流
|
||||
|
||||
1. 接收 PM 侧 UR、RA、SA。
|
||||
2. 使用 `se-requirement-review` 判断工程就绪度。
|
||||
3. 对阻塞问题回传 PM。
|
||||
4. 使用 `se-requirement-analysis` 生成 OR、DR。
|
||||
5. 更新 case 的 `traceability.md`。
|
||||
6. 进入 Gate 2 研发需求评审。
|
||||
7. 评审通过后交给 RD。
|
||||
@@ -0,0 +1,124 @@
|
||||
# 全局 Agent 规则
|
||||
|
||||
以下是本机 Codex 的个人工作约定；系统、开发者、项目级 `AGENTS.md` 和当前用户明确要求始终优先。
|
||||
|
||||
## 个人偏好
|
||||
|
||||
- 默认使用简体中文；代码标识符、命令、配置键和路径保持原文。
|
||||
- 结论先行；以当前机器、仓库、会话和真实运行结果为准。
|
||||
- 默认做最小充分实现，不扩张范围，不覆盖、还原或提交用户已有改动。
|
||||
- 最终答复只保留结论、关键证据、实际验证、剩余风险和必要下一步。
|
||||
|
||||
## 授权边界
|
||||
|
||||
- 用户只要求回答、解释、分析、诊断、review 或规划时，只读检查并报告；不得修改产品代码或外部状态。
|
||||
- 用户明确要求修改、实现、构建或修复时，完成范围内本地改动和非破坏性验证，不重复索要实现确认。
|
||||
- 外部系统写入、发送、发布、破坏性操作、付费、权限变更和实质扩张范围前必须确认。
|
||||
- Review-only 只报告 findings；只有用户同时要求修复时才修改代码。
|
||||
- Diagnosis-only 交付根因、证据和建议；只有用户同时要求修复时才实现。
|
||||
- 没有直接验证证据时，不声称完成、通过、可提交或可合并。
|
||||
|
||||
## 任务分流
|
||||
|
||||
分流由本文件与项目 `.trellis/workflow.md` 共同决定，顺序如下：
|
||||
|
||||
1. 当前用户明确指定的 workflow 或 skill。
|
||||
2. 明确属于 Inline 的简单任务。
|
||||
3. 非简单但能在单会话完成的工程任务，使用当前最匹配的 Matt 方法。
|
||||
4. 已有 `.trellis/` 且任务需要跨会话、多项稳定决策、多交付物或 durable research 时，进入 Trellis 生命周期并在其中使用 Matt 方法。
|
||||
|
||||
### Inline
|
||||
|
||||
以下任务直接处理，不创建 Trellis task：
|
||||
|
||||
- 一轮可完成的问答、解释、代码阅读；
|
||||
- 局部配置、文案或单文件修改；
|
||||
- 根因明确的小修；
|
||||
- 影响范围窄、没有需要持久化的设计决策；
|
||||
- 当前上下文内可以完成最小验证。
|
||||
|
||||
### Matt
|
||||
|
||||
- 按当前可用 skill 的 `description` 路由，不在全局规则复制完整 skill 清单。
|
||||
- 用户明确点名且可用的 skill 优先；多个匹配时选范围最窄的一个。
|
||||
- 用户要求 `/tdd`、test-first、red-green-refactor 或 integration tests 时使用 `/tdd`，并先确认要测试的公开 seam。
|
||||
- 没有精确匹配时由主会话执行标准闭环：证据 → 决策/计划 → 执行 → 验证。
|
||||
- 所选 skill 的流程门禁有效，但不得扩大当前用户授权。
|
||||
|
||||
### Trellis + Matt
|
||||
|
||||
- Trellis 只管理 task 状态、planning artifacts、research、checkpoint、跨会话恢复和 archive。
|
||||
- Matt 只提供当前阶段的工程方法；一个阶段只保留一个 method owner。
|
||||
- Phase 1 不使用 `trellis-brainstorm`：主会话先基于证据形成 task artifacts，再用 `grill-with-docs` review spec。
|
||||
- Phase 2 不使用原生 `trellis-implement`：由 `trellis-matt-implement` sub-agent 按已记录的 `standard|tdd` mode 执行；agent 不可用时由主会话按同一 mode fallback。
|
||||
- Trellis 详细 phase、breadcrumb、恢复和归档命令以项目 `.trellis/workflow.md` 为准。
|
||||
- 简单工作不建 task；项目没有 `.trellis/` 时不主动初始化，除非用户明确要求长期记录或初始化。
|
||||
|
||||
## Planning 方法
|
||||
|
||||
- Trellis task 的 `prd.md`、条件性的 `design.md` 和 `implement.md` 是 task-level spec source of truth。
|
||||
- Planning artifacts 初稿应来自代码、测试、配置、文档和 task history 等证据。
|
||||
- 每个 Trellis implementation task 在 `prd.md` 的 `Testing Strategy` 记录 `Implementation Mode: standard|tdd`；默认 `standard`。
|
||||
- 用户要求 `/tdd`、test-first、red-green-refactor、integration tests 或 reviewed spec 明确要求 TDD 时记录 `tdd`，并在进入执行前确认公开测试 seam。
|
||||
- 使用 `grill-with-docs` 逐项 review 产品、范围、UX、兼容、风险、验收和关键设计决策。
|
||||
- 一次只问一个问题；先查环境事实，只把真正属于用户的决策交给用户。
|
||||
- 每个答案确认后立即同步回 owning Trellis artifact。
|
||||
- `CONTEXT.md` 只保存稳定领域术语；ADR 只保存难以逆转、反直觉且经过真实取舍的决策，不复制 task spec。
|
||||
- `grill-with-docs` wrapper 不可加载时，使用 `grilling` + `domain-modeling` 的等价组合。
|
||||
- 用户确认 shared understanding 后，视为 spec review 完成；不再增加独立的 Trellis implementation approval。
|
||||
|
||||
## Implementation 方法
|
||||
|
||||
- 以 review 完成的 Trellis artifacts 或当前 spec/tickets 作为实现输入。
|
||||
- Matt 单会话任务由主会话执行 implementation contract；Trellis Phase 2 由主会话派发 `trellis-matt-implement` 执行被委派的实现切片。
|
||||
- `trellis-matt-implement` 是 execution role，不在 sub-agent 内调用 Matt `/implement` wrapper；每个实现切片只有一个 method owner。
|
||||
- Dispatch prompt 必须包含 `Active task: <task-path>`、`Implementation mode: standard|tdd` 和 confirmed TDD seams；agent 按 `implement.jsonl`（如有真实条目）→ `prd.md` → `design.md`（如有）→ `implement.md`（如有）读取上下文。
|
||||
- `standard` 是默认模式：先完成最小、连贯的实现增量，再运行单测试文件、受影响 type-check 等窄反馈，并在行为存在后按需补充验收/回归测试。
|
||||
- `tdd` 只在用户触发且公开 seam 已确认时启用：显式加载 `/tdd`，按一个 failing behavioral test → 最小 green implementation 的 vertical slice 循环。
|
||||
- TDD seam 未确认或 `/tdd` 不可加载时返回 `blocked`，不得自行选择、推断或静默降级模式。
|
||||
- TDD red → green loop 内不做无关 refactor；refactor 留到主会话最终 review，之后重跑行为测试和完整适用验证。
|
||||
- 两种模式结束时都运行完整适用验证。
|
||||
- Sub-agent 不修改 Trellis task 状态、requirements 或 acceptance criteria，不执行 Git 写操作，也不派发其他 agent。
|
||||
- Sub-agent 返回后由主会话检查完整 diff、同步 checkpoint，并按当前可用 review skill 的 `description` 完成最终 review 和 acceptance；该 skill 明确要求并行时可以使用子 agent。
|
||||
- Matt `implement` 中无条件 commit 的步骤不适用；commit 仍由下方版本控制规则约束。
|
||||
|
||||
## Codex 执行方式
|
||||
|
||||
- 默认由主会话完成探索、规划、检查和验收；Trellis Phase 2 是明确例外，由当前 workflow 派发 `trellis-matt-implement` 完成实现切片。
|
||||
- 默认只派发一个 `trellis-matt-implement`；只有独立 child task 或写入范围完全分离时，才按 workflow/skill 的明确要求并行。
|
||||
- 不因为 Trellis 的默认 dispatch banner 自动派发原生 `trellis-implement`。
|
||||
- `trellis-matt-implement` 不可用、无法可靠加载 task context 或平台不支持 custom sub-agent 时，由主会话按已记录 mode fallback：`standard` 使用 Matt 适配契约，`tdd` 显式加载 `/tdd`。
|
||||
- 子 agent 只拥有被委派的窄任务；主会话负责范围、整合、验收和用户沟通。
|
||||
|
||||
## Spec 与经验提升
|
||||
|
||||
- 每个任务都可以判断是否产生了值得提升的知识，但默认不执行 promotion。
|
||||
- 只有知识稳定、可复用、已经验证且用户明确确认后，才写入 `.trellis/spec/`、全局规则、skill、hook、test、script 或跨项目知识库。
|
||||
- 未满足条件的内容保留在当前 task 的 design/research/retrospective，或在最终答复中列为 candidate。
|
||||
|
||||
## 工具与代码约定
|
||||
|
||||
- 搜索文件和文本优先使用 `rg` / `rg --files`。
|
||||
- 当前项目存在 `.codegraph/` 且任务涉及跨文件改动、重构、影响分析或调用链排查时，按项目约定优先使用 CodeGraph。
|
||||
- 查询 library、framework、SDK、API、CLI 或 cloud service 的当前行为时，使用项目指定的最新文档工具；本地版本和真实运行结果优先。
|
||||
- 编写函数、类或复杂逻辑时使用对应文档注释，说明参数、返回值、异常与设计原因。
|
||||
- 注释解释 Why，不逐行翻译代码；权限、安全和兼容边界旁添加显眼警告。
|
||||
|
||||
## 版本控制
|
||||
|
||||
- commit、push、PR 只在用户明确要求时执行，三者授权互不自动包含。
|
||||
- Trellis archive 和 journal 使用命令级 `--no-commit`；不依赖自动提交。
|
||||
- commit message 默认 `<type>(scope): <中文动词短语>`，不加句号。
|
||||
- commit 只包含本任务已确认归属的文件；不 amend，不静默包含用户或其他并行工作的改动。
|
||||
|
||||
## 最终答复
|
||||
|
||||
结论先行，按实际需要包含：
|
||||
|
||||
1. outcome；
|
||||
2. key evidence / changed files；
|
||||
3. verification actually run；
|
||||
4. remaining risks or blockers；
|
||||
5. necessary next step。
|
||||
|
||||
省略过程复述。未运行的验证必须明确写 `not run` 或说明阻塞原因。
|
||||
@@ -0,0 +1,576 @@
|
||||
# Yuxuanhui Development Workflow
|
||||
|
||||
> 适用范围：已经初始化 `.trellis/` 的项目。
|
||||
>
|
||||
> 设计基线：Trellis 0.6.8。本文可作为项目 `.trellis/workflow.md` 的轻量单文件覆盖版本。
|
||||
>
|
||||
> 定制契约参考：[Trellis 官方「定制 Workflow」](https://docs.trytrellis.app/zh/advanced/custom-workflow)。
|
||||
|
||||
## 0. Workflow Contract
|
||||
|
||||
### Instruction precedence
|
||||
|
||||
上层指令、项目 `AGENTS.md` 和用户当前明确要求始终优先。发生冲突时，不用 workflow 或 skill 扩大用户授权。
|
||||
|
||||
### Three operating modes
|
||||
|
||||
| Mode | Owner | Use when | Persistence |
|
||||
| -------------- | ------------------------------------ | ----------------------- | --------------------------------------------------- |
|
||||
| Inline | 主会话 | 简单、局部、根因明确、一个上下文内可完成 | 不创建 Trellis task |
|
||||
| Matt | 当前匹配的工程 skill；无匹配时为主会话 | 非简单但仍可单会话完成的工程工作 | 使用现有项目产物，不强制创建 task |
|
||||
| Trellis + Matt | Trellis 管生命周期；当前匹配的 Matt skill 管工程方法 | 跨会话、多项稳定决策、多交付物或明确要求持久化 | task、planning artifacts、research、checkpoint、archive |
|
||||
|
||||
Trellis 是控制面，不替代工程方法；Matt 是方法层，不拥有 task 状态。一个阶段只选择一个方法 owner，禁止把多个完整 workflow 叠加执行。Trellis 的上下文加载、状态写入和归档动作不算第二个方法 owner。
|
||||
|
||||
### Lightweight override policy
|
||||
|
||||
本方案在项目侧覆盖 `.trellis/workflow.md`，并新增 `.codex/agents/trellis-matt-implement.toml`；配套 `AGENTS.md` 可放在全局或项目层。不要求修改 `.trellis/config.yaml`、Codex hooks 或 Trellis bundled skills。为避免旧入口重新接管流程，遵循以下覆盖规则：
|
||||
|
||||
- 全局 `AGENTS.md` 与本文共同拥有任务分流权；Trellis bundled skill 不得覆盖二者。
|
||||
- `trellis-start` 只用于加载 context、phase 和 spec indexes；忽略其中旧的 task-consent 与固定 skill route。
|
||||
- 不调用 `trellis-brainstorm` 和原生 `trellis-implement`。Planning 使用 `grill-with-docs`；Trellis Phase 2 使用 `trellis-matt-implement` 执行本工作流适配后的 Matt implementation contract。
|
||||
- 不依赖 `trellis-continue` 的旧 route table；恢复逻辑以本文 `Active Task Routing` 为准。
|
||||
- 不调用 `trellis-finish-work` 的旧 commit-first 流程；直接运行本文 3.5 的 `--no-commit` 命令。
|
||||
- 即使 Codex hook 的 `<codex-mode>` banner 显示 Trellis sub-agent 默认值，本文对 planning/implementation 方法的明确选择优先：不得派发原生 `trellis-implement`。
|
||||
- `trellis-matt-implement` 是本 workflow 明确选择的 Phase 2 execution role，默认只派发一个。每个实现切片的方法 owner 只能是 `standard` Matt contract 或显式 `/tdd` 之一；其他子 agent 仅在用户明确要求，或当前选中的 Matt skill 自身明确要求并行时启用。
|
||||
|
||||
### Core principles
|
||||
|
||||
1. **Evidence before inference** — 以当前机器、仓库、任务文件、diff 和真实命令输出为准。
|
||||
2. **Minimum sufficient work** — 完成用户要求的最小充分范围，不顺手扩张，不覆盖用户已有改动。
|
||||
3. **Persist only when useful** — 简单工作留在会话；跨会话状态、稳定决策和可复用证据才写入 Trellis。
|
||||
4. **One lifecycle owner, one method owner** — Trellis 管状态；当前阶段只选择一个工程方法。
|
||||
5. **Verification before completion claims** — 没有直接验证证据时，不声称完成、通过、可提交或可合并。
|
||||
6. **No implicit external effects** — 外部写入、发送、发布、破坏性操作、付费、权限变更和实质扩张范围前必须确认。
|
||||
7. **No implicit promotion or version control** — spec promotion、commit、push、PR 都不是默认收尾动作。
|
||||
|
||||
## 1. Request Routing
|
||||
|
||||
### Step A: Determine the user's authorized intent
|
||||
|
||||
| User intent | Default boundary |
|
||||
| --- | --- |
|
||||
| 回答、解释、分析、诊断、review、规划 | 只读检查并报告；不得修改产品代码或外部状态 |
|
||||
| 修改、实现、构建、修复 | 完成范围内本地改动和非破坏性验证；不重复索要实现确认 |
|
||||
| 外部系统写入、发布、破坏性操作、付费、权限变更、实质扩张范围 | 执行前确认 |
|
||||
| spec promotion | 仅在知识稳定、可复用、已验证且用户确认后执行 |
|
||||
| commit、push、PR | 仅在用户明确要求时执行；三者授权互不自动包含 |
|
||||
|
||||
只读请求进入 Trellis 时，可以写 task 自身的 planning/research/checkpoint 产物，但不得把“记录分析”解释成“允许修代码”。Review-only 请求即使发现问题也只报告；只有用户同时要求修复时才改。
|
||||
|
||||
### Step B: Choose the lifecycle mode
|
||||
|
||||
#### Inline
|
||||
|
||||
满足以下条件时直接处理，不创建 task：
|
||||
|
||||
- 一轮可完成的问答、解释或代码阅读；
|
||||
- 局部配置、文案或单文件修改；
|
||||
- 根因已经明确的小修；
|
||||
- 影响范围窄、没有需要长期保存的设计决策；
|
||||
- 最小验证能在当前上下文完成。
|
||||
|
||||
#### Matt without Trellis
|
||||
|
||||
不属于 Inline，但仍能在一个健康上下文内完成，且不需要持久化多项决策时：
|
||||
|
||||
- 按当前可用 skill 的 `description` 选择最窄、最精确的方法；
|
||||
- 在主会话完成，除非所选 skill 自身明确要求并行 agent；
|
||||
- 不为“显得正式”而创建 Trellis task。
|
||||
|
||||
#### Trellis + Matt
|
||||
|
||||
出现任一条件时进入 Trellis 生命周期：
|
||||
|
||||
- 用户明确要求使用 Trellis、长期记录或跨会话恢复；
|
||||
- 工作很可能跨会话或需要 handoff；
|
||||
- 存在两项及以上会影响后续实现的稳定决策；
|
||||
- 一个请求包含多个可独立验证的交付物；
|
||||
- 需要持久化 research、兼容/迁移方案、rollout/rollback 或重要风险；
|
||||
- 当前已有匹配该请求的 active task。
|
||||
|
||||
若边界不确定，优先先用 Matt 单会话模式；只有在工作实际出现跨会话、独立交付物或持久决策需求时再升级为 Trellis。升级时把已确认事实、决策、剩余工作和验证证据写入 task，然后继续；不要从头重做。
|
||||
|
||||
### Method selection details
|
||||
|
||||
Trellis 生命周期内有两个固定替换：
|
||||
|
||||
- Phase 1 不使用 `trellis-brainstorm`；先由主会话基于证据形成 planning artifacts，再用 `grill-with-docs` review 和压实 spec。
|
||||
- Phase 2 不使用原生 `trellis-implement`；派发 `trellis-matt-implement` 按已经 review 的 artifacts 执行适配后的 Matt implementation contract。
|
||||
|
||||
其他意图不要在本文件复制一份会过期的 Matt skill 清单。按以下顺序路由：
|
||||
|
||||
1. 用户明确点名且当前可用的 skill 优先。
|
||||
2. 用户要求 `/tdd`、test-first、red-green-refactor 或 integration tests 时选择 `/tdd`；Trellis task 必须先持久化 `Implementation Mode: tdd` 并确认公开测试 seam。
|
||||
3. 否则扫描当前可用 skill 的 `description`，匹配当前阶段的真实意图，例如需求拷问、spec/issue、实现、诊断、review、架构或 research。
|
||||
4. 多个 skill 都匹配时，选择范围最窄、产物最贴近当前阶段的一个。
|
||||
5. 所选 skill 的硬性门禁仍然有效；它明确要求并行 agent 时，视为允许该阶段使用子 agent。
|
||||
6. 没有精确匹配时，由主会话采用标准闭环：证据 → 决策/计划 → 执行 → 验证。
|
||||
7. 不得仅因为某个 skill 曾属于 Matt 的历史主流程，就调用当前不可用或不匹配的 skill。
|
||||
|
||||
`grill-with-docs` 当前属于显式调用型 skill；`trellis-matt-implement` 是本 workflow 选择的 Codex custom execution role，不在 sub-agent 内调用 Matt `/implement` wrapper。它按 planning artifact 中的模式执行且不得自行推断 TDD：
|
||||
|
||||
- `standard` 是默认方法：先完成稳定实现增量，再运行窄检查和按需补充测试；
|
||||
- `tdd` 仅在用户触发且公开 seam 已确认时使用：sub-agent 显式加载 `/tdd`，按 vertical red → green slice 实施。
|
||||
|
||||
对应能力不可用时：
|
||||
|
||||
- `grill-with-docs` fallback 为 `grilling` + `domain-modeling`；
|
||||
- `trellis-matt-implement` fallback 由主会话按已记录模式执行：`standard` 遵循本工作流覆盖后的 Matt contract；`tdd` 显式加载 `/tdd`。两种模式都不执行隐式 Git 写操作。
|
||||
|
||||
## 2. Trellis System
|
||||
|
||||
### Task lifecycle
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<title>" --slug <name>
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
python3 ./.trellis/scripts/task.py finish
|
||||
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
|
||||
python3 ./.trellis/scripts/task.py list [--mine] [--status <status>]
|
||||
python3 ./.trellis/scripts/task.py list-archive
|
||||
```
|
||||
|
||||
- `create` 创建 `status=planning` 的 task；若会话标识可用，会设置 session-scoped active task。
|
||||
- `start` 把 task 切到 `in_progress`；它只表示进入执行阶段，不扩大用户授权。
|
||||
- `finish` 只清除当前会话指针，不改变 task status，也不表示任务完成。
|
||||
- `archive --no-commit` 写入 `status=completed`、移动 task 并清除相关会话指针，但不得触碰 Git。
|
||||
- 归档和 journal 始终显式传入 `--no-commit`，因此无需修改 `session_auto_commit` 默认值。
|
||||
- 以 `python3 ./.trellis/scripts/task.py --help` 为 CLI 命令事实源；不要使用实际 help 中不存在的子命令。
|
||||
|
||||
### Planning artifacts
|
||||
|
||||
| Artifact | Rule |
|
||||
| --- | --- |
|
||||
| `prd.md` | 每个 Trellis task 必需；记录目标、事实、范围、约束、验收标准、开放决策，以及 `Testing Strategy` 中的 implementation mode / TDD seams |
|
||||
| `design.md` | 跨模块、契约、兼容、迁移、安全、rollout/rollback 或存在重要技术取舍时需要 |
|
||||
| `implement.md` | 多步骤、跨会话、风险较高或需要明确验证顺序时需要 |
|
||||
| `research/*.md` | 只保存会影响决策且需要跨会话保留的研究；一题一文件，记录来源和结论 |
|
||||
| `implement.jsonl` | `trellis-matt-implement` 的可选 context manifest；有真实 spec/research 条目时先读取，只有 seed 时允许由 agent 自行发现相关规范 |
|
||||
| `check.jsonl` | 本 workflow 不使用原生 Trellis check sub-agent；保留生成的 seed 即可，不需要维护 |
|
||||
|
||||
`prd.md` 不放详细技术设计和执行 checklist。`design.md` 解释技术形状与取舍。`implement.md` 记录有序步骤、验证命令、风险、rollback point 和当前 checkpoint。
|
||||
|
||||
每个 Trellis implementation task 在 `prd.md` 中维护：
|
||||
|
||||
```markdown
|
||||
## Testing Strategy
|
||||
|
||||
- Implementation Mode: standard | tdd
|
||||
- Confirmed TDD Seams: Not applicable | <confirmed public seams>
|
||||
```
|
||||
|
||||
`standard` 是默认值。只有用户明确要求 `/tdd`、test-first、red-green-refactor、integration tests，或已经 review 的 spec 明确要求 TDD 时才写 `tdd`；没有已确认 seam 时不得进入 TDD execution。
|
||||
|
||||
跨会话 task 的 `implement.md` 必须维护一个简短 checkpoint：
|
||||
|
||||
```markdown
|
||||
## Current Checkpoint
|
||||
|
||||
- Last completed:
|
||||
- Evidence:
|
||||
- Next:
|
||||
- Blockers:
|
||||
```
|
||||
|
||||
Checkpoint 只记录恢复所需状态，不复述聊天过程。
|
||||
|
||||
### Parent / child tasks
|
||||
|
||||
只有当交付物能够独立规划、实现、检查和归档时才创建 child task。优先采用窄而完整的纵向切片；单纯按技术层横切通常不构成 child。
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child> --parent <parent-dir>
|
||||
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
|
||||
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
|
||||
```
|
||||
|
||||
父子关系不是依赖图。阻塞顺序必须明确写在 child 的 `prd.md` 或 `implement.md`。父 task 管源需求、task map、跨 child 验收和最终集成；下一步只激活真正拥有交付物的 child。
|
||||
|
||||
## Phase Index
|
||||
|
||||
```text
|
||||
Route: Inline | Matt | Trellis + Matt
|
||||
Phase 1: Plan → persist evidence, decisions, acceptance and execution shape
|
||||
Phase 2: Execute → perform only the actions authorized by the user's intent
|
||||
Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and report
|
||||
```
|
||||
|
||||
### Request triage
|
||||
|
||||
- 无 active task 时先静默分类，不询问“要不要创建 Trellis task”这类纯流程问题。
|
||||
- Inline 和 Matt 单会话工作直接开始。
|
||||
- 满足 Trellis 条件时自动创建 task；用户明确要求实现/修复，已经同时授权范围内本地实现，不需要在 planning 结束后重复确认。
|
||||
- 用户只要求规划、review 或诊断时，即使创建 task 也不获得产品代码修改授权。
|
||||
- 若仍有用户拥有的产品、范围、兼容、风险或验收决策，只问一个最高价值问题并等待答案。
|
||||
- 用户明确说“不建 task”时尊重；若范围已不适合单会话，缩小交付物或说明无法可靠持久化的风险。
|
||||
- 项目不存在 `.trellis/` 时不得主动初始化，除非用户明确要求长期记录或初始化。
|
||||
|
||||
### Skill Routing
|
||||
|
||||
| User intent / phase | Route |
|
||||
| --- | --- |
|
||||
| 简单、局部、根因明确 | Inline；不创建 task |
|
||||
| 非简单但单会话可完成 | 按当前 skill `description` 选择 Matt 方法 |
|
||||
| 明确 `/tdd`、test-first、red-green-refactor 或 integration tests | `/tdd`；Trellis task 先记录 mode 并确认公开 seam |
|
||||
| Trellis planning artifact review | `grill-with-docs`；不用 `trellis-brainstorm` |
|
||||
| Trellis reviewed spec implementation | `trellis-matt-implement`；不用原生 `trellis-implement`；不可用时主会话执行 Matt fallback |
|
||||
| 诊断、review、架构、research | 按当前 skill `description` 选择最窄匹配 |
|
||||
| Trellis 状态、恢复、归档 | 本文 Phase、Active Task Routing 与 `.trellis/scripts/` |
|
||||
|
||||
### Phase 1 summary
|
||||
|
||||
- 1.0 Create or resume task `[required · once]`
|
||||
- 1.1 Draft planning artifacts from evidence `[required · repeatable]`
|
||||
- 1.2 Research / prototype / design inquiry `[optional · repeatable]`
|
||||
- 1.3 Review spec with `grill-with-docs` `[required · once]`
|
||||
- 1.4 Activate or stop at planning boundary `[required · once]`
|
||||
- 1.5 Planning completion criteria
|
||||
|
||||
[workflow-state:no_task]
|
||||
Route by `AGENTS.md`: Inline for simple work, Matt for single-session engineering, Trellis only for durable work. Do not ask task-consent questions.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
[workflow-state:no_task-inline]
|
||||
Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a task only for durable work; do not ask task-consent questions.
|
||||
[/workflow-state:no_task-inline]
|
||||
|
||||
[workflow-state:planning]
|
||||
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, then route by the user's original intent.
|
||||
[/workflow-state:planning]
|
||||
|
||||
[workflow-state:planning-inline]
|
||||
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, and sync decisions. Trellis artifacts remain task-level truth.
|
||||
[/workflow-state:planning-inline]
|
||||
|
||||
### Phase 2 summary
|
||||
|
||||
- 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
|
||||
- 2.2 Quality and acceptance check `[required · repeatable]`
|
||||
- 2.3 Roll back to the right phase `[on demand]`
|
||||
|
||||
[workflow-state:in_progress]
|
||||
Never dispatch native `trellis-implement`. Dispatch one `trellis-matt-implement` with `Active task`, recorded implementation mode, and confirmed TDD seams. After it returns, verify the full diff and update the checkpoint. Commit remains user-requested only.
|
||||
[/workflow-state:in_progress]
|
||||
|
||||
[workflow-state:in_progress-inline]
|
||||
Main session follows the recorded mode: adapted Matt contract for `standard`, `/tdd` for `tdd`. Dispatch neither native `trellis-implement` nor `trellis-matt-implement`. Commit only when explicitly requested.
|
||||
[/workflow-state:in_progress-inline]
|
||||
|
||||
### Phase 3 summary
|
||||
|
||||
- 3.2 Debug retrospective `[on demand]`
|
||||
- 3.3 Knowledge promotion decision `[required · once]`
|
||||
- 3.4 Version-control actions `[on explicit request]`
|
||||
- 3.5 Archive, journal and report `[required · once]`
|
||||
|
||||
[workflow-state:completed]
|
||||
Archive and journal with `--no-commit`, then report outcome, verification and remaining risk. Never infer commit, push, PR or spec-promotion permission.
|
||||
[/workflow-state:completed]
|
||||
|
||||
### Phase rules
|
||||
|
||||
1. 先识别用户授权边界，再识别 lifecycle mode 和当前 phase。
|
||||
2. Phase 内按顺序执行 required steps；已有且仍有效的产物不重复生成。
|
||||
3. 新证据推翻需求或设计时可以回到 Phase 1；回退后更新 owning artifact，再继续。
|
||||
4. 一个阶段只有一个工程方法 owner。另一个 skill 只有在当前 owner 明确委托时才能作为子步骤运行。
|
||||
5. 会话接近上下文质量边界时，先更新 task checkpoint，再切换会话；不要靠模糊摘要继续硬撑。
|
||||
6. 工作中途从 Inline/Matt 升级到 Trellis 时，保留已有证据和结果，不重新执行已完成步骤。
|
||||
|
||||
## Phase 1: Plan
|
||||
|
||||
Goal：把 durable 工作变成可恢复、可验收的 task，同时不制造重复确认。
|
||||
|
||||
#### 1.0 Create or resume task `[required · once]`
|
||||
|
||||
先检查当前 task：
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
```
|
||||
|
||||
- 当前 active task 与请求匹配：读取并继续，不新建。
|
||||
- 请求不满足 Trellis 条件：退出 Trellis 路径，改走 Inline 或 Matt。
|
||||
- 请求满足 Trellis 条件：直接创建 task，不询问流程性同意。
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
|
||||
```
|
||||
|
||||
这里只运行 `create`，不要紧接着无条件 `start`。先把用户原始意图、证据和必要 planning artifacts 写清楚。
|
||||
|
||||
若一个请求包含多个可独立验证交付物，先建立 parent/child map。不要仅因文件多或跨层就拆 child；交付物能独立验收才拆。
|
||||
|
||||
#### 1.1 Draft planning artifacts from evidence `[required · repeatable]`
|
||||
|
||||
1. 读取现有代码、测试、配置、文档、spec、历史 task 和 git 状态。
|
||||
2. 把仓库可回答的问题直接查清，不反问用户事实。
|
||||
3. 区分：已确认事实、用户意图、范围/风险决策、技术未知项、明确 out of scope。
|
||||
4. 由主会话先形成 `prd.md`，并在触发条件成立时形成 `design.md`、`implement.md`。
|
||||
5. 在 `prd.md` 的 `Testing Strategy` 记录 mode。默认 `standard`；用户要求 `/tdd`、test-first、red-green-refactor、integration tests 或 reviewed spec 明确要求 TDD 时记录 `tdd`，并列出待确认的公开 seam。
|
||||
6. 若实现 agent 需要固定读取某些 spec/research，把真实条目加入 `implement.jsonl`；不登记产品代码。没有额外 context 时允许保留 seed，由 agent 自行发现相关规范。
|
||||
7. 每次重要结论形成后立即更新 owning artifact，避免只留在聊天里。
|
||||
8. 暂不使用 `trellis-brainstorm`；开放决策和 TDD seam 留给 1.3 的 `grill-with-docs` 逐项 review。
|
||||
|
||||
`prd.md` 至少包含：Goal、Background/Evidence、In Scope、Out of Scope、Requirements、Acceptance Criteria、Constraints、Open Decisions、Testing Strategy。
|
||||
|
||||
完成前做一次收敛检查：删除重复事实和已解决问题，保留所有证据锚点、约束、决策和验收映射。
|
||||
|
||||
#### 1.2 Research / prototype / design inquiry `[optional · repeatable]`
|
||||
|
||||
当技术事实无法由仓库直接回答时再 research；当状态模型、业务逻辑或 UI 必须运行/观察才能决策时才 prototype；当接口、seam、domain vocabulary 或架构形状是问题本身时选择对应设计方法。
|
||||
|
||||
Research 规则：
|
||||
|
||||
- 优先官方文档、标准、源码和一手 API；
|
||||
- 按项目 `AGENTS.md` 使用指定的当前文档工具；
|
||||
- 对 Trellis task，把会影响实现的结论写入 `{TASK_DIR}/research/<topic>.md`；
|
||||
- 记录来源、版本/日期、结论、适用范围和未决风险；
|
||||
- research 提供证据，不替用户作产品决策。
|
||||
|
||||
Prototype 规则：代码从一开始就视为 throwaway；保留答案，不把原型未经重新设计直接并入产品实现。
|
||||
|
||||
#### 1.3 Review spec with `grill-with-docs` `[required · once]`
|
||||
|
||||
显式加载 `grill-with-docs`，用它 review `prd.md`、条件性的 `design.md` 和 `implement.md`：
|
||||
|
||||
1. 先由环境证据回答事实问题，不把仓库可查事实反问用户。
|
||||
2. 对产品、范围、UX、兼容、风险、验收和关键设计决策逐项 grilling。
|
||||
3. 一次只问一个问题，每个问题提供推荐答案和不同选择的取舍。
|
||||
4. 每个答案确认后立即同步到 owning Trellis artifact。
|
||||
5. `Implementation Mode: tdd` 时，按 `/tdd` 契约确认要观察的公开 interface/seam；未确认前不写测试、不进入 Phase 2。`standard` 不询问 TDD seam。
|
||||
6. `CONTEXT.md` 只记录稳定领域术语；ADR 只记录难以逆转、反直觉且经过真实取舍的决策。
|
||||
7. Trellis artifacts 始终是当前 task 的 spec source of truth；不要让 glossary/ADR 复制任务细节。
|
||||
|
||||
`grill-with-docs` 在平台上不可直接加载时，使用其等价组合：`grilling` + `domain-modeling`。
|
||||
|
||||
当用户确认已经达到 shared understanding 时，本步骤完成。这个确认是 spec review 的完成条件，不再额外增加一层 Trellis implementation approval。
|
||||
|
||||
#### 1.4 Activate or stop at planning boundary `[required · once]`
|
||||
|
||||
按授权矩阵处理：
|
||||
|
||||
| Situation | Action |
|
||||
| --- | --- |
|
||||
| 用户明确要求 implement/build/fix/change；artifacts ready；无未决用户决策 | 直接运行 `task.py start` 并进入 Phase 2，不重复询问 |
|
||||
| 用户只要求 plan/spec/review/diagnose | 停在授权边界；交付所请求产物或进入只读执行，不修改产品代码 |
|
||||
| 所选 skill 自身有明确的人类门禁 | 遵循该门禁 |
|
||||
| 涉及外部写入、破坏性操作、付费、权限、实质扩张 | 先确认对应动作 |
|
||||
| artifacts 发生实质范围变化且原授权已不覆盖 | 先请求方向 |
|
||||
|
||||
启动命令：
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
```
|
||||
|
||||
原始实现请求加上 1.3 的 shared-understanding 确认已经构成实现授权；不再额外增加 Trellis planning approval。
|
||||
|
||||
Planning-only task 的 planning 产物本身就是交付物；完成并验证后可直接进入 3.5 归档，不必为了走形式而把它切到 `in_progress`。
|
||||
|
||||
#### 1.5 Planning completion criteria
|
||||
|
||||
| Condition | Required |
|
||||
| --- | :---: |
|
||||
| `prd.md` 有可观察的 acceptance criteria | ✅ |
|
||||
| 仓库可回答的事实已有证据 | ✅ |
|
||||
| 阻塞性用户决策为空 | ✅ |
|
||||
| `design.md` 在触发条件成立时存在 | ✅ |
|
||||
| `implement.md` 在触发条件成立时存在并有 checkpoint | ✅ |
|
||||
| research 结论已持久化（如有） | ✅ |
|
||||
| `Testing Strategy` 已记录 `standard` 或 `tdd` | ✅ |
|
||||
| `tdd` 模式的公开测试 seam 已由用户确认 | 条件性 ✅ |
|
||||
| `grill-with-docs` review 已达到 shared understanding | ✅ |
|
||||
| 当前动作仍处于用户授权范围 | ✅ |
|
||||
|
||||
## Phase 2: Execute
|
||||
|
||||
Goal：按一个明确方法完成被授权的工作，并留下可复核证据。
|
||||
|
||||
#### 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
|
||||
|
||||
执行前：
|
||||
|
||||
1. 读取 `prd.md`、条件性的 `design.md` / `implement.md`、相关 research。
|
||||
2. 运行 package/spec discovery，读取受影响范围的 pre-development checklist 和具体规范。
|
||||
3. 检查 `git status`，区分任务内改动、用户已有改动和无关并行工作。
|
||||
4. 当前项目存在 `.codegraph/` 且任务属于跨文件改动、重构、影响分析或调用链排查时，按项目 `AGENTS.md` 优先使用 CodeGraph。
|
||||
5. 读取 `Testing Strategy`：只接受 `standard` 或 `tdd`。`tdd` 缺 confirmed seam 时回到 1.3；不得在 Phase 2 自行选择或猜测 TDD。
|
||||
6. 用 `task.py current --source` 取得当前会话的精确 task path，确认 task 与请求匹配且状态为 `in_progress`。
|
||||
7. 派发一个 `trellis-matt-implement`；不得派发原生 `trellis-implement`。Dispatch prompt 必须带精确 task path、mode 和 seams：
|
||||
|
||||
```text
|
||||
Active task: <task-path>
|
||||
Implementation mode: <standard | tdd>
|
||||
Confirmed TDD seams:
|
||||
- <public seam, or Not applicable>
|
||||
Implement only <delegated slice> from the reviewed task artifacts.
|
||||
Do not change task state, dispatch another agent, or perform Git writes.
|
||||
```
|
||||
|
||||
Agent contract：
|
||||
|
||||
- `trellis-matt-implement` 是 execution role，不在 sub-agent 内调用 Matt `/implement` wrapper；每个切片只能选择一种 implementation method；
|
||||
- 按 `implement.jsonl` 真实条目 → `prd.md` → 条件性的 `design.md` → 条件性的 `implement.md` → 相关项目规范读取 context；
|
||||
- 以已经 review 的 Trellis artifacts 作为 spec/tickets，只做被委派切片覆盖的最小充分实现；
|
||||
- 不覆盖、还原或提交用户已有改动；
|
||||
- 公开函数、类和复杂逻辑遵循项目注释规范，解释设计原因和关键边界；
|
||||
- `standard`：不采用 TDD/test-first；先完成稳定实现增量，再运行相关单测试文件、受影响 type-check 等窄反馈，并按需在实现行为存在后补充验收/回归测试；
|
||||
- `tdd`：必须显式加载 `/tdd`，只在 confirmed public seams 上按一个 failing behavior test → 最小 green implementation 的 vertical slice 循环；skill 不可加载或 seam 缺失时返回 `blocked`，不得自行降级；
|
||||
- TDD red → green loop 内不做无关 refactor；把候选项交给主会话在 2.2 review 阶段处理；
|
||||
- 两种模式都在切片结束时运行完整适用验证；
|
||||
- 不修改 task 状态、requirements、scope 或 acceptance criteria，不执行 Git 写操作，不继续派发 agent；
|
||||
- 完成后 self-review 整个被委派切片，并返回 implementation mode、confirmed seams、changed files、acceptance mapping、真实验证结果和剩余风险。
|
||||
|
||||
Agent 返回后，主会话必须检查报告和完整 diff，把已完成步骤、验证证据、下一步和 blocker 同步到 `implement.md` Current Checkpoint，再进入 2.2。诊断/review-only task 不得派发实现 agent 或因为“顺手”而修改产品代码。
|
||||
|
||||
若 custom agent 不可用、无法可靠获得 task context 或平台不支持 custom sub-agent，由主会话按已记录模式执行：`standard` 使用适配后的 Matt fallback，`tdd` 显式加载 `/tdd`。默认一次只派发一个实现 agent；只有独立 child task 或写入范围完全分离时才允许并行。任何 commit 仍只在用户明确要求后进入 3.4。
|
||||
|
||||
#### 2.2 Quality and acceptance check `[required · repeatable]`
|
||||
|
||||
检查方式取决于用户意图：
|
||||
|
||||
- 实现/修复任务：可以在范围内修复检查发现的问题，然后重跑验证。
|
||||
- Review-only：只报告 findings，不修改。
|
||||
- Diagnosis-only：报告根因、证据和建议，不实现修复。
|
||||
|
||||
每轮至少检查：
|
||||
|
||||
1. diff 与 `prd.md` acceptance criteria 的逐项映射；
|
||||
2. 适用 `.trellis/spec/` 和项目规范；
|
||||
3. 受影响范围的 lint、type-check、tests、build 或其他真实验收命令；
|
||||
4. 跨层数据流、类型、错误传播、兼容和回归影响（如适用）；
|
||||
5. 未运行的检查及原因。
|
||||
|
||||
最终一轮必须覆盖整个 task diff，而不是只检查最后一个 patch。记录命令、退出结果和关键输出；工具未实际运行时只能写 `not run` 或 `blocked`，不得写 `passed`。
|
||||
|
||||
若 implementation mode 为 `tdd`，refactor 只在本 review 阶段进行；完成后重跑受影响的行为测试和完整适用验证，确保 green 状态没有被破坏。
|
||||
|
||||
若所选 review skill 明确要求多个独立 review agent，则该并行是 Matt implementation method 的内部步骤。没有匹配或它无法覆盖当前未提交 diff 时，由主会话直接做完整 diff review；不要为形式再叠加 `trellis-check`。
|
||||
|
||||
#### 2.3 Roll back to the right phase `[on demand]`
|
||||
|
||||
- 新证据说明 requirement/acceptance 有误 → 回 Phase 1，更新 `prd.md`。
|
||||
- 接口、兼容、迁移或架构形状有误 → 回 Phase 1，更新 `design.md` 和 `implement.md`。
|
||||
- 缺技术事实 → 回 1.2 research，并持久化结论。
|
||||
- 实现偏离但需求正确 → 只撤销或改正本任务自己造成的改动，再做 2.1。
|
||||
- 不得用 destructive Git 命令清理工作树，不得还原无法确认归属的用户改动。
|
||||
|
||||
## Phase 3: Finish
|
||||
|
||||
Goal：用证据关闭交付物，区分任务记录、知识提升和版本控制三种不同动作。
|
||||
|
||||
#### 3.2 Debug retrospective `[on demand]`
|
||||
|
||||
只有出现重复失败、同一问题多次修复、昂贵绕路或难以建立反馈回路时才复盘。选择当前最匹配的 diagnosis/learning 方法，记录：
|
||||
|
||||
- 根因；
|
||||
- 早期方案为何失败；
|
||||
- 最终证据为何可信；
|
||||
- 可以预防同类问题的候选知识。
|
||||
|
||||
普通任务总结不触发复盘。
|
||||
|
||||
#### 3.3 Knowledge promotion decision `[required · once]`
|
||||
|
||||
必须做“是否值得提升”的判断，但默认不修改 `.trellis/spec/` 或跨项目知识库。
|
||||
|
||||
候选知识只有同时满足以下条件才可 promotion：
|
||||
|
||||
1. 稳定：不是一次性实现细节或临时 workaround；
|
||||
2. 可复用：未来任务会据此作出不同且更好的行动；
|
||||
3. 已验证：有代码、测试、文档或重复证据支持；
|
||||
4. 用户确认：明确同意把它提升为 spec、skill、hook、test、script 或跨项目 pattern。
|
||||
|
||||
未获确认时：
|
||||
|
||||
- 可以保留在当前 task 的 design/research/retrospective 中；
|
||||
- 在最终答复中列为 promotion candidate；
|
||||
- 不得自动写入 `.trellis/spec/` 或个人知识库的 canonical 区域。
|
||||
|
||||
用户确认后，选择当前可用的 spec/compound-learning 方法执行，并验证新增规则与当前仓库事实一致。
|
||||
|
||||
#### 3.4 Version-control actions `[on explicit request]`
|
||||
|
||||
默认跳过所有 Git 写操作。只有用户明确要求时才执行对应动作：
|
||||
|
||||
- commit：仅包含本任务已知改动；先检查 dirty state 和 recent history；按逻辑单元分组；默认 message 为 `<type>(scope): <中文动词短语>`，不加句号；不 amend。
|
||||
- push：仅在明确要求 push 时执行；commit 授权不包含 push。
|
||||
- PR：仅在明确要求创建 PR 时执行；commit/push 授权不包含 PR。
|
||||
|
||||
Trellis 不自动提交 task archive 或 journal；3.5 的命令始终显式使用 `--no-commit`。
|
||||
|
||||
#### 3.5 Archive, journal and report `[required · once]`
|
||||
|
||||
先判断 task 是否真的完成：acceptance criteria 已满足，必要检查已有直接证据，阻塞项为空；否则只更新 checkpoint 和风险，不 archive。
|
||||
|
||||
完成后归档：
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
|
||||
```
|
||||
|
||||
记录 session：
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "<title>" \
|
||||
--summary "<outcome, verification, remaining risk>" \
|
||||
--no-commit
|
||||
```
|
||||
|
||||
命令级 `--no-commit` 保证这两个命令只写文件，不 stage、commit 或 push，因此无需改动 `.trellis/config.yaml`。只有本次任务已经按用户明确要求生成 work commit 时，才额外传入 `--commit "<hashes>"`；否则省略该参数，不得伪造 hash。
|
||||
|
||||
最终答复结论先行，只保留：
|
||||
|
||||
1. outcome；
|
||||
2. key evidence / changed files；
|
||||
3. verification actually run；
|
||||
4. remaining risks or blockers；
|
||||
5. necessary next step（仅在确有必要时）。
|
||||
|
||||
没有直接验证证据时，不写“完成”“通过”“可提交”“可合并”。
|
||||
|
||||
## Active Task Routing
|
||||
|
||||
Active task 存在时，先读取 `task.json`、artifacts 和 Current Checkpoint，再按状态继续：
|
||||
|
||||
| Status / evidence | Resume action |
|
||||
| --- | --- |
|
||||
| `planning`，`prd.md` 未收敛 | 1.1 |
|
||||
| `planning`，存在技术未知项 | 1.2 |
|
||||
| `planning`，artifacts 尚未通过 `grill-with-docs` review | 1.3 |
|
||||
| `planning`，shared understanding 已确认 | 1.4；按用户原始意图 start 或停在 planning boundary |
|
||||
| `in_progress`，checkpoint 指向未完成实现/诊断/review | 2.1 |
|
||||
| `in_progress`，执行完成但缺 full-scope evidence | 2.2 |
|
||||
| `in_progress`，acceptance 已验证 | 3.3 → 条件性 3.4 → 3.5 |
|
||||
| `completed` 仍可解析 | 3.5 report；正常 archive 后 active pointer 通常已清除 |
|
||||
|
||||
用户在 active task 中提出无关的简单问题时，可以 Inline 回答，不修改 task。用户明确切换到另一个 durable 工作时，先保存当前 checkpoint，再激活新 task；不要把两个需求混进同一 task。
|
||||
|
||||
## Runtime and Customization Invariants
|
||||
|
||||
1. `.trellis/workflow.md` 是 workflow 语义和 breadcrumb 文本的 source of truth。
|
||||
2. 修改 required steps 时，同步更新对应 `[workflow-state:*]` block。
|
||||
3. opening/closing workflow-state tag 的 status 必须完全相同；status 只使用 `[A-Za-z0-9_-]+`。
|
||||
4. 不新增 custom task status，除非同时更新 status writer、breadcrumb 和本文 Active Task Routing。
|
||||
5. 本 workflow 保留 Trellis 现有 Phase/step 编号，降低 `get_context.py --mode phase --step <X.Y>` 和 platform entry files 的漂移。
|
||||
6. 若 bundled skill/command 与本文冲突，以用户指令、`AGENTS.md` 和本文为准；使用本文给出的底层 Trellis 命令，不修改 bundled 文件。
|
||||
7. `trellis update` 之后检查 `.new` sidecar 或 template conflict，不得直接覆盖个人定制。
|
||||
8. Breadcrumb 保持简短；详细规则放 Phase 正文。Phase Index 与详细 Phase 必须同步。
|
||||
9. `agents/codex/trellis-matt-implement.toml` 是 custom implement agent 的共享 source of truth；项目安装位置为 `.codex/agents/trellis-matt-implement.toml`。
|
||||
10. Agent 依赖 dispatch prompt 中的精确 `Active task:` 路径做 pull-based context loading；本方案不要求把新名称加入 Codex hook matcher。
|
||||
11. Implementation mode 只允许 `standard` / `tdd`；`tdd` 必须同时存在用户触发和 confirmed public seam，agent 不得自行升级模式。
|
||||
|
||||
## Adoption Checklist
|
||||
|
||||
- [ ] 把本文件作为项目 `.trellis/workflow.md`。
|
||||
- [ ] 把配套指引作为全局或项目 `AGENTS.md`。
|
||||
- [ ] 把 `agents/codex/trellis-matt-implement.toml` 复制到项目 `.codex/agents/trellis-matt-implement.toml`。
|
||||
- [ ] 用无 task、planning、in_progress 三种状态分别验证 Codex breadcrumb。
|
||||
- [ ] 用 `standard` 测试 task 验证 agent 不运行 TDD，并通过 `Active task:` 读取 artifacts。
|
||||
- [ ] 用 `tdd` 测试 task 验证 agent 只在 confirmed seam 上加载 `/tdd` 并执行 vertical red → green slices。
|
||||
- [ ] 两种模式都验证 agent 不运行 task lifecycle 或 Git 写操作。
|
||||
- [ ] 验证 `task.py archive` 和 `add_session.py` 输出包含跳过 stage/commit 的证据。
|
||||
- [ ] 下一条用户消息验证 breadcrumb；新开会话验证 Phase 正文与 Skill Routing 生效。
|
||||
@@ -0,0 +1,124 @@
|
||||
# Global Agent Rules
|
||||
|
||||
The following are my personal operating conventions for Codex on this machine. System instructions, developer instructions, project-level `AGENTS.md`, and the user's current explicit request always take precedence.
|
||||
|
||||
## Personal Preferences
|
||||
|
||||
- Use Simplified Chinese by default; keep code identifiers, commands, configuration keys, and paths unchanged.
|
||||
- Lead with the conclusion and rely on evidence from the current machine, repository, session, and actual command results.
|
||||
- Default to the minimum sufficient implementation. Do not expand scope or overwrite, revert, or commit the user's existing changes.
|
||||
- Keep the final response to the outcome, key evidence, verification actually performed, remaining risks, and any necessary next step.
|
||||
|
||||
## Authorization Boundaries
|
||||
|
||||
- When the user only asks for an answer, explanation, analysis, diagnosis, review, or plan, inspect in read-only mode and report the result. Do not modify product code or external state.
|
||||
- When the user explicitly asks to modify, implement, build, or fix something, complete the in-scope local changes and non-destructive verification without asking again for implementation approval.
|
||||
- Confirm before writing to an external system, sending or publishing anything, performing a destructive action, incurring a charge, changing permissions, or materially expanding scope.
|
||||
- Review-only work reports findings only. Modify code only when the user also asks for a fix.
|
||||
- Diagnosis-only work delivers the root cause, evidence, and recommendation. Implement a fix only when the user also asks for one.
|
||||
- Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
|
||||
|
||||
## Task Routing
|
||||
|
||||
Routing is jointly determined by this file and the project's `.trellis/workflow.md`, in the following order:
|
||||
|
||||
1. A workflow or skill explicitly requested by the user.
|
||||
2. Simple work that clearly belongs to Inline mode.
|
||||
3. Engineering work that is not simple but can be completed in one session, using the most appropriate current Matt method.
|
||||
4. When `.trellis/` exists and the work requires multiple sessions, several durable decisions, multiple deliverables, or durable research, enter the Trellis lifecycle and use Matt methods within it.
|
||||
|
||||
### Inline
|
||||
|
||||
Handle the following directly without creating a Trellis task:
|
||||
|
||||
- A question, explanation, or code-reading task that can be completed in one turn;
|
||||
- A local configuration, copy, or single-file change;
|
||||
- A small fix with a known root cause;
|
||||
- Work with a narrow impact and no design decision that needs to persist;
|
||||
- Work whose minimum verification can be completed in the current context.
|
||||
|
||||
### Matt
|
||||
|
||||
- Route by the `description` of currently available skills instead of copying a complete skill list into these global rules.
|
||||
- Prefer an available skill explicitly named by the user. If several skills match, choose the narrowest one.
|
||||
- Use `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, and first confirm the public seams to test.
|
||||
- When there is no exact match, the main session performs the standard loop: evidence → decision/plan → execution → verification.
|
||||
- The selected skill's workflow gates remain in force, but must not expand the user's current authorization.
|
||||
|
||||
### Trellis + Matt
|
||||
|
||||
- Trellis manages only task state, planning artifacts, research, checkpoints, cross-session recovery, and archiving.
|
||||
- Matt provides only the engineering method for the current phase. Keep exactly one method owner per phase.
|
||||
- Do not use `trellis-brainstorm` in Phase 1. The main session first drafts task artifacts from evidence, then reviews the spec with `grill-with-docs`.
|
||||
- Do not use the native `trellis-implement` in Phase 2. The `trellis-matt-implement` sub-agent executes the recorded `standard|tdd` mode; if the agent is unavailable, the main session falls back using the same mode.
|
||||
- Follow the project's `.trellis/workflow.md` for detailed phases, breadcrumbs, recovery, and archive commands.
|
||||
- Do not create a task for simple work. If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.
|
||||
|
||||
## Planning Method
|
||||
|
||||
- A Trellis task's `prd.md` and conditional `design.md` and `implement.md` are the task-level source of truth for the spec.
|
||||
- Initial planning artifacts should come from evidence in code, tests, configuration, documentation, and task history.
|
||||
- Every Trellis implementation task records `Implementation Mode: standard|tdd` under `Testing Strategy` in `prd.md`; `standard` is the default.
|
||||
- Record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and confirm public test seams before execution.
|
||||
- Use `grill-with-docs` to review product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
|
||||
- Ask one question at a time. Investigate environmental facts first and ask the user only for decisions that genuinely belong to them.
|
||||
- After each answer is confirmed, immediately synchronize it back to the owning Trellis artifact.
|
||||
- `CONTEXT.md` stores only durable domain terminology. ADRs store only decisions that are hard to reverse, counterintuitive, and based on a real tradeoff; they must not duplicate the task spec.
|
||||
- If the `grill-with-docs` wrapper cannot be loaded, use the equivalent combination of `grilling` + `domain-modeling`.
|
||||
- Once the user confirms shared understanding, the spec review is complete. Do not add a separate Trellis implementation approval.
|
||||
|
||||
## Implementation Method
|
||||
|
||||
- Use reviewed Trellis artifacts or the current spec/tickets as implementation input.
|
||||
- For a single-session Matt task, the main session executes the implementation contract. In Trellis Phase 2, the main session dispatches `trellis-matt-implement` for the delegated implementation slice.
|
||||
- `trellis-matt-implement` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each implementation slice has exactly one method owner.
|
||||
- The dispatch prompt must contain `Active task: <task-path>`, `Implementation mode: standard|tdd`, and confirmed TDD seams. The agent reads context in this order: real `implement.jsonl` entries when present → `prd.md` → optional `design.md` → optional `implement.md`.
|
||||
- `standard` is the default: complete the smallest coherent implementation increment before narrow feedback such as a single test file or affected type-check, then add acceptance/regression tests as needed after the behavior exists.
|
||||
- Enable `tdd` only after a user trigger and confirmation of public seams: explicitly load `/tdd` and work in vertical slices of one failing behavioral test → minimum green implementation.
|
||||
- If TDD seams are unconfirmed or `/tdd` cannot be loaded, return `blocked`; never select, infer, or silently downgrade the mode.
|
||||
- Do not perform unrelated refactoring inside the TDD red → green loop. Refactor during the main session's final review, then rerun behavioral tests and all applicable full-scope verification.
|
||||
- Run all applicable full-scope verification at the end of either mode.
|
||||
- The sub-agent does not change Trellis task state, requirements, or acceptance criteria; perform Git writes; or dispatch other agents.
|
||||
- After the sub-agent returns, the main session inspects the complete diff, synchronizes the checkpoint, and performs final review and acceptance through the `description` of currently available review skills. Sub-agents may be used when that skill explicitly requires parallel work.
|
||||
- Any unconditional commit step in Matt `implement` does not apply. Commits remain governed by the version-control rules below.
|
||||
|
||||
## Codex Execution
|
||||
|
||||
- By default, the main session performs exploration, planning, checks, and acceptance. Trellis Phase 2 is an explicit exception: the current workflow dispatches `trellis-matt-implement` for the implementation slice.
|
||||
- Dispatch only one `trellis-matt-implement` by default. Use parallel agents only for independent child tasks or completely disjoint write scopes when explicitly required by the workflow/skill.
|
||||
- Do not automatically dispatch the native `trellis-implement` because of a Trellis default dispatch banner.
|
||||
- If `trellis-matt-implement` is unavailable, cannot load task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt contract for `standard`, or explicitly load `/tdd` for `tdd`.
|
||||
- A sub-agent owns only the narrow task delegated to it. The main session owns scope, integration, acceptance, and user communication.
|
||||
|
||||
## Spec and Learning Promotion
|
||||
|
||||
- Every task may evaluate whether it produced knowledge worth promoting, but promotion is not performed by default.
|
||||
- Write to `.trellis/spec/`, global rules, a skill, hook, test, script, or cross-project knowledge base only when the knowledge is durable, reusable, verified, and explicitly approved by the user.
|
||||
- Keep anything that does not meet those conditions in the current task's design, research, or retrospective, or list it as a candidate in the final response.
|
||||
|
||||
## Tool and Code Conventions
|
||||
|
||||
- Prefer `rg` / `rg --files` for file and text searches.
|
||||
- When the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by the project conventions.
|
||||
- When checking the current behavior of a library, framework, SDK, API, CLI, or cloud service, use the current-documentation tool required by the project. Prefer the locally installed version and actual runtime results.
|
||||
- When writing functions, classes, or complex logic, use the corresponding documentation-comment format and describe parameters, return values, exceptions, and design rationale.
|
||||
- Comments explain why, not a line-by-line translation of the code. Add prominent warnings beside permission, security, and compatibility boundaries.
|
||||
|
||||
## Version Control
|
||||
|
||||
- Commit, push, and PR actions require an explicit user request, and authorization for one does not imply authorization for another.
|
||||
- Trellis archive and journal commands use command-level `--no-commit`; do not rely on automatic commits.
|
||||
- Commit messages default to `<type>(scope): <Chinese verb phrase>` with no trailing period.
|
||||
- A commit contains only files confirmed to belong to the current task. Do not amend or silently include the user's changes or changes from parallel work.
|
||||
|
||||
## Final Response
|
||||
|
||||
Lead with the conclusion and include only what is needed:
|
||||
|
||||
1. Outcome;
|
||||
2. Key evidence / changed files;
|
||||
3. Verification actually run;
|
||||
4. Remaining risks or blockers;
|
||||
5. Necessary next step.
|
||||
|
||||
Omit a process recap. Any verification that was not run must be marked `not run` or accompanied by the reason it was blocked.
|
||||
@@ -0,0 +1,576 @@
|
||||
# Yuxuanhui Development Workflow
|
||||
|
||||
> Scope: projects where `.trellis/` has already been initialized.
|
||||
>
|
||||
> Design baseline: Trellis 0.6.8. This document can be used as a lightweight, single-file override for the project's `.trellis/workflow.md`.
|
||||
>
|
||||
> Customization contract reference: [Trellis official “Custom Workflow” documentation](https://docs.trytrellis.app/zh/advanced/custom-workflow).
|
||||
|
||||
## 0. Workflow Contract
|
||||
|
||||
### Instruction precedence
|
||||
|
||||
Higher-level instructions, the project `AGENTS.md`, and the user's current explicit request always take precedence. When a conflict occurs, do not use this workflow or a skill to expand the user's authorization.
|
||||
|
||||
### Three operating modes
|
||||
|
||||
| Mode | Owner | Use when | Persistence |
|
||||
| -------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| Inline | Main session | Simple, local, root cause known, and completable in one context | No Trellis task |
|
||||
| Matt | The currently matched engineering skill; otherwise the main session | Engineering work that is not simple but can still be completed in one session | Use existing project artifacts; no task is required |
|
||||
| Trellis + Matt | Trellis owns the lifecycle; the currently matched Matt skill owns the engineering method | Multiple sessions, several durable decisions, multiple deliverables, or explicit persistence | Task, planning artifacts, research, checkpoint, archive |
|
||||
|
||||
Trellis is the control plane and does not replace the engineering method. Matt is the method layer and does not own task state. Select exactly one workflow owner for each phase; do not stack multiple complete workflows. Trellis context loading, state writes, and archive actions do not count as a second method owner.
|
||||
|
||||
### Lightweight override policy
|
||||
|
||||
At project level, this setup overrides `.trellis/workflow.md` and adds `.codex/agents/trellis-matt-implement.toml`; the companion `AGENTS.md` may live globally or in the project. It does not require changes to `.trellis/config.yaml`, Codex hooks, or Trellis bundled skills. To prevent legacy entry points from taking control again, apply these override rules:
|
||||
|
||||
- Global `AGENTS.md` and this document jointly own task routing. Trellis bundled skills must not override either one.
|
||||
- Use `trellis-start` only to load context, phase, and spec indexes. Ignore its legacy task-consent and fixed skill routing.
|
||||
- Do not call `trellis-brainstorm` or the native `trellis-implement`. Planning uses `grill-with-docs`; Trellis Phase 2 uses `trellis-matt-implement` to execute the Matt implementation contract adapted by this workflow.
|
||||
- Do not depend on the legacy route table in `trellis-continue`. Use this document's `Active Task Routing`.
|
||||
- Do not call the legacy commit-first flow in `trellis-finish-work`. Run the `--no-commit` commands in section 3.5 directly.
|
||||
- Even if a Codex hook's `<codex-mode>` banner shows Trellis sub-agent defaults, the explicit planning and implementation method selected here takes precedence. Never dispatch the native `trellis-implement`.
|
||||
- `trellis-matt-implement` is the Phase 2 execution role explicitly selected by this workflow; dispatch only one by default. Each implementation slice has exactly one method owner: either the `standard` Matt contract or explicit `/tdd`. Enable other sub-agents only when the user explicitly requests them or the currently selected Matt skill explicitly requires parallel work.
|
||||
|
||||
### Core principles
|
||||
|
||||
1. **Evidence before inference** — Rely on the current machine, repository, task files, diff, and actual command output.
|
||||
2. **Minimum sufficient work** — Complete the smallest sufficient scope requested by the user. Do not expand scope or overwrite existing user changes.
|
||||
3. **Persist only when useful** — Keep simple work in the session. Write only cross-session state, durable decisions, and reusable evidence to Trellis.
|
||||
4. **One lifecycle owner, one method owner** — Trellis manages state; each phase selects exactly one engineering method.
|
||||
5. **Verification before completion claims** — Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
|
||||
6. **No implicit external effects** — Confirm before external writes, sending, publishing, destructive actions, paid actions, permission changes, or material scope expansion.
|
||||
7. **No implicit promotion or version control** — Spec promotion, commit, push, and PR are never default finishing actions.
|
||||
|
||||
## 1. Request Routing
|
||||
|
||||
### Step A: Determine the user's authorized intent
|
||||
|
||||
| User intent | Default boundary |
|
||||
| --- | --- |
|
||||
| Answer, explain, analyze, diagnose, review, or plan | Inspect in read-only mode and report; do not modify product code or external state |
|
||||
| Modify, implement, build, or fix | Complete in-scope local changes and non-destructive verification; do not ask again for implementation approval |
|
||||
| External-system write, publish, destructive action, paid action, permission change, or material scope expansion | Confirm before execution |
|
||||
| Spec promotion | Perform only when the knowledge is durable, reusable, verified, and confirmed by the user |
|
||||
| Commit, push, or PR | Perform only when explicitly requested; authorization for one does not imply authorization for another |
|
||||
|
||||
When a read-only request enters Trellis, the task's own planning, research, and checkpoint artifacts may be written, but “record the analysis” must not be interpreted as “permission to fix the code.” A review-only request reports issues even when it finds them. Modify code only when the user also asks for a fix.
|
||||
|
||||
### Step B: Choose the lifecycle mode
|
||||
|
||||
#### Inline
|
||||
|
||||
Handle the work directly without creating a task when all relevant conditions are satisfied:
|
||||
|
||||
- A question, explanation, or code-reading task that can be completed in one turn;
|
||||
- A local configuration, copy, or single-file change;
|
||||
- A small fix with a known root cause;
|
||||
- A narrow impact with no design decision that needs long-term persistence;
|
||||
- Minimum verification that can be completed in the current context.
|
||||
|
||||
#### Matt without Trellis
|
||||
|
||||
When the task is not Inline but can still be completed in one healthy context and does not need several decisions to persist:
|
||||
|
||||
- Select the narrowest, most precise method from currently available skill `description` values;
|
||||
- Complete it in the main session unless the selected skill explicitly requires parallel agents;
|
||||
- Do not create a Trellis task merely to make the work appear formal.
|
||||
|
||||
#### Trellis + Matt
|
||||
|
||||
Enter the Trellis lifecycle when any of the following applies:
|
||||
|
||||
- The user explicitly asks for Trellis, durable records, or cross-session recovery;
|
||||
- The work is likely to span sessions or require handoff;
|
||||
- Two or more durable decisions will affect later implementation;
|
||||
- One request contains multiple independently verifiable deliverables;
|
||||
- Research, compatibility/migration plans, rollout/rollback plans, or important risks must persist;
|
||||
- An active task already matches the request.
|
||||
|
||||
When the boundary is uncertain, prefer Matt in a single session first. Upgrade to Trellis only when the work actually develops cross-session needs, independent deliverables, or durable decisions. On upgrade, record confirmed facts, decisions, remaining work, and verification evidence in the task, then continue without repeating completed work.
|
||||
|
||||
### Method selection details
|
||||
|
||||
The Trellis lifecycle has two fixed substitutions:
|
||||
|
||||
- Phase 1 does not use `trellis-brainstorm`. The main session first drafts planning artifacts from evidence, then uses `grill-with-docs` to review and tighten the spec.
|
||||
- Phase 2 does not use the native `trellis-implement`. Dispatch `trellis-matt-implement` to execute the adapted Matt implementation contract from the reviewed artifacts.
|
||||
|
||||
For other intents, do not copy a Matt skill list into this file where it can become stale. Route in this order:
|
||||
|
||||
1. Prefer a currently available skill explicitly named by the user.
|
||||
2. Select `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests. A Trellis task must first persist `Implementation Mode: tdd` and confirm its public test seams.
|
||||
3. Otherwise, scan the `description` of current skills and match the actual intent of the current phase, such as requirements interrogation, spec/issue work, implementation, diagnosis, review, architecture, or research.
|
||||
4. If several skills match, select the narrowest one whose output best fits the current phase.
|
||||
5. Mandatory gates of the selected skill remain in force. If it explicitly requires parallel agents, sub-agents are permitted for that phase.
|
||||
6. If there is no exact match, the main session uses the standard loop: evidence → decision/plan → execution → verification.
|
||||
7. Do not call an unavailable or mismatched skill merely because it historically belonged to a Matt primary workflow.
|
||||
|
||||
`grill-with-docs` is currently an explicit-invocation skill. `trellis-matt-implement` is the Codex custom execution role selected by this workflow and does not call a Matt `/implement` wrapper inside the sub-agent. It follows the mode recorded in planning artifacts and never infers TDD:
|
||||
|
||||
- `standard` is the default method: complete a stable implementation increment, then run narrow checks and add tests as needed;
|
||||
- `tdd` is used only after a user trigger and confirmation of public seams: the sub-agent explicitly loads `/tdd` and works in vertical red → green slices.
|
||||
|
||||
When the corresponding capability is unavailable:
|
||||
|
||||
- The `grill-with-docs` fallback is `grilling` + `domain-modeling`;
|
||||
- The `trellis-matt-implement` fallback is the main session following the recorded mode: the Matt contract overridden by this workflow for `standard`, or an explicitly loaded `/tdd` for `tdd`. Neither mode performs implicit Git writes.
|
||||
|
||||
## 2. Trellis System
|
||||
|
||||
### Task lifecycle
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<title>" --slug <name>
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
python3 ./.trellis/scripts/task.py finish
|
||||
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
|
||||
python3 ./.trellis/scripts/task.py list [--mine] [--status <status>]
|
||||
python3 ./.trellis/scripts/task.py list-archive
|
||||
```
|
||||
|
||||
- `create` creates a task with `status=planning`. If a session identifier is available, it sets the session-scoped active task.
|
||||
- `start` changes the task to `in_progress`. It only indicates entry into the execution phase and does not expand user authorization.
|
||||
- `finish` only clears the current session pointer. It does not change task status or mean that the task is complete.
|
||||
- `archive --no-commit` writes `status=completed`, moves the task, and clears related session pointers without touching Git.
|
||||
- Always pass `--no-commit` explicitly to archive and journal commands, so changing the `session_auto_commit` default is unnecessary.
|
||||
- Treat `python3 ./.trellis/scripts/task.py --help` as the source of truth for CLI commands. Do not use subcommands absent from the actual help output.
|
||||
|
||||
### Planning artifacts
|
||||
|
||||
| Artifact | Rule |
|
||||
| --- | --- |
|
||||
| `prd.md` | Required for every Trellis task; records goals, facts, scope, constraints, acceptance criteria, open decisions, and implementation mode / TDD seams under `Testing Strategy` |
|
||||
| `design.md` | Required for cross-module work, contracts, compatibility, migration, security, rollout/rollback, or important technical tradeoffs |
|
||||
| `implement.md` | Required for multi-step, cross-session, or higher-risk work, or when the verification sequence must be explicit |
|
||||
| `research/*.md` | Store only research that affects decisions and must persist across sessions; one question per file, with sources and conclusions |
|
||||
| `implement.jsonl` | Optional context manifest for `trellis-matt-implement`; read real spec/research entries first, while a seed-only manifest allows the agent to discover relevant standards itself |
|
||||
| `check.jsonl` | This workflow does not use the native Trellis check sub-agent; keep the generated seed as-is without maintaining it |
|
||||
|
||||
Do not put detailed technical design or an execution checklist in `prd.md`. `design.md` explains the technical shape and tradeoffs. `implement.md` records ordered steps, verification commands, risks, rollback points, and the current checkpoint.
|
||||
|
||||
Every Trellis implementation task maintains this in `prd.md`:
|
||||
|
||||
```markdown
|
||||
## Testing Strategy
|
||||
|
||||
- Implementation Mode: standard | tdd
|
||||
- Confirmed TDD Seams: Not applicable | <confirmed public seams>
|
||||
```
|
||||
|
||||
`standard` is the default. Write `tdd` only when the user explicitly requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD. TDD execution cannot begin without at least one confirmed seam.
|
||||
|
||||
Every cross-session task must maintain a short checkpoint in `implement.md`:
|
||||
|
||||
```markdown
|
||||
## Current Checkpoint
|
||||
|
||||
- Last completed:
|
||||
- Evidence:
|
||||
- Next:
|
||||
- Blockers:
|
||||
```
|
||||
|
||||
The checkpoint records only the state needed for recovery, not a recap of the conversation.
|
||||
|
||||
### Parent / child tasks
|
||||
|
||||
Create a child task only when its deliverable can be planned, implemented, checked, and archived independently. Prefer narrow but complete vertical slices. A split by technical layer alone usually does not justify a child task.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child> --parent <parent-dir>
|
||||
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
|
||||
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
|
||||
```
|
||||
|
||||
Parent-child relationships are not a dependency graph. Write blocking order explicitly in the child's `prd.md` or `implement.md`. The parent task owns source requirements, the task map, cross-child acceptance, and final integration. Activate next only the child that owns a real deliverable.
|
||||
|
||||
## Phase Index
|
||||
|
||||
```text
|
||||
Route: Inline | Matt | Trellis + Matt
|
||||
Phase 1: Plan → persist evidence, decisions, acceptance and execution shape
|
||||
Phase 2: Execute → perform only the actions authorized by the user's intent
|
||||
Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and report
|
||||
```
|
||||
|
||||
### Request triage
|
||||
|
||||
- When there is no active task, classify silently first. Do not ask process-only questions such as whether to create a Trellis task.
|
||||
- Start Inline and single-session Matt work directly.
|
||||
- When Trellis conditions are met, create the task automatically. An explicit user request to implement or fix already authorizes in-scope local implementation; do not ask again after planning.
|
||||
- When the user asks only for planning, review, or diagnosis, creating a task does not grant permission to modify product code.
|
||||
- If a product, scope, compatibility, risk, or acceptance decision still belongs to the user, ask only the single highest-value question and wait for the answer.
|
||||
- Respect an explicit request not to create a task. If the scope is no longer suitable for one session, narrow the deliverable or explain the risk of unreliable persistence.
|
||||
- If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.
|
||||
|
||||
### Skill Routing
|
||||
|
||||
| User intent / phase | Route |
|
||||
| --- | --- |
|
||||
| Simple, local, root cause known | Inline; no task |
|
||||
| Not simple but completable in one session | Select a Matt method from current skill `description` values |
|
||||
| Explicit `/tdd`, test-first, red-green-refactor, or integration tests | `/tdd`; for Trellis, first record the mode and confirm public seams |
|
||||
| Trellis planning artifact review | `grill-with-docs`; do not use `trellis-brainstorm` |
|
||||
| Trellis reviewed-spec implementation | `trellis-matt-implement`; do not use the native `trellis-implement`; use the main-session Matt fallback when unavailable |
|
||||
| Diagnosis, review, architecture, or research | Select the narrowest match from current skill `description` values |
|
||||
| Trellis state, recovery, or archive | This document's phases, `Active Task Routing`, and `.trellis/scripts/` |
|
||||
|
||||
### Phase 1 summary
|
||||
|
||||
- 1.0 Create or resume task `[required · once]`
|
||||
- 1.1 Draft planning artifacts from evidence `[required · repeatable]`
|
||||
- 1.2 Research / prototype / design inquiry `[optional · repeatable]`
|
||||
- 1.3 Review spec with `grill-with-docs` `[required · once]`
|
||||
- 1.4 Activate or stop at planning boundary `[required · once]`
|
||||
- 1.5 Planning completion criteria
|
||||
|
||||
[workflow-state:no_task]
|
||||
Route by `AGENTS.md`: Inline for simple work, Matt for single-session engineering, Trellis only for durable work. Do not ask task-consent questions.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
[workflow-state:no_task-inline]
|
||||
Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a task only for durable work; do not ask task-consent questions.
|
||||
[/workflow-state:no_task-inline]
|
||||
|
||||
[workflow-state:planning]
|
||||
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, then route by the user's original intent.
|
||||
[/workflow-state:planning]
|
||||
|
||||
[workflow-state:planning-inline]
|
||||
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, and sync decisions. Trellis artifacts remain task-level truth.
|
||||
[/workflow-state:planning-inline]
|
||||
|
||||
### Phase 2 summary
|
||||
|
||||
- 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
|
||||
- 2.2 Quality and acceptance check `[required · repeatable]`
|
||||
- 2.3 Roll back to the right phase `[on demand]`
|
||||
|
||||
[workflow-state:in_progress]
|
||||
Never dispatch the native `trellis-implement`. Dispatch one `trellis-matt-implement` with `Active task`, the recorded implementation mode, and confirmed TDD seams. After it returns, verify the full diff and update the checkpoint. Commit remains user-requested only.
|
||||
[/workflow-state:in_progress]
|
||||
|
||||
[workflow-state:in_progress-inline]
|
||||
Main session follows the recorded mode: the adapted Matt contract for `standard`, `/tdd` for `tdd`. Dispatch neither the native `trellis-implement` nor `trellis-matt-implement`. Commit only when explicitly requested.
|
||||
[/workflow-state:in_progress-inline]
|
||||
|
||||
### Phase 3 summary
|
||||
|
||||
- 3.2 Debug retrospective `[on demand]`
|
||||
- 3.3 Knowledge promotion decision `[required · once]`
|
||||
- 3.4 Version-control actions `[on explicit request]`
|
||||
- 3.5 Archive, journal and report `[required · once]`
|
||||
|
||||
[workflow-state:completed]
|
||||
Archive and journal with `--no-commit`, then report outcome, verification and remaining risk. Never infer commit, push, PR or spec-promotion permission.
|
||||
[/workflow-state:completed]
|
||||
|
||||
### Phase rules
|
||||
|
||||
1. Identify the user's authorization boundary first, then the lifecycle mode and current phase.
|
||||
2. Run required steps in order within a phase. Do not recreate artifacts that already exist and remain valid.
|
||||
3. If new evidence invalidates a requirement or design, return to Phase 1. Update the owning artifact before continuing.
|
||||
4. Each phase has one engineering-method owner. Another skill may run as a substep only when the current owner explicitly delegates to it.
|
||||
5. When a session approaches the context-quality boundary, update the task checkpoint before switching sessions. Do not continue by relying on a vague summary.
|
||||
6. When work upgrades from Inline/Matt to Trellis midstream, preserve existing evidence and results. Do not repeat completed steps.
|
||||
|
||||
## Phase 1: Plan
|
||||
|
||||
Goal: turn durable work into a recoverable, testable task without creating duplicate approval gates.
|
||||
|
||||
#### 1.0 Create or resume task `[required · once]`
|
||||
|
||||
Check the current task first:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
```
|
||||
|
||||
- If the active task matches the request, read it and continue without creating another.
|
||||
- If the request does not meet Trellis conditions, leave the Trellis path and use Inline or Matt.
|
||||
- If the request meets Trellis conditions, create the task directly without asking for process consent.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
|
||||
```
|
||||
|
||||
Run only `create` here. Do not immediately and unconditionally run `start`. First record the user's original intent, evidence, and required planning artifacts clearly.
|
||||
|
||||
If one request contains multiple independently verifiable deliverables, first create a parent/child map. Do not split into child tasks merely because the work spans several files or layers; split only when a deliverable can be accepted independently.
|
||||
|
||||
#### 1.1 Draft planning artifacts from evidence `[required · repeatable]`
|
||||
|
||||
1. Read existing code, tests, configuration, documentation, specs, historical tasks, and Git state.
|
||||
2. Investigate questions the repository can answer directly instead of asking the user for facts.
|
||||
3. Distinguish confirmed facts, user intent, scope/risk decisions, technical unknowns, and explicit out-of-scope items.
|
||||
4. The main session first drafts `prd.md`, plus `design.md` and `implement.md` when their conditions apply.
|
||||
5. Record the mode under `Testing Strategy` in `prd.md`. Default to `standard`; record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and list candidate public seams for confirmation.
|
||||
6. If the implementation agent must read specific specs or research, add real entries to `implement.jsonl`; do not register product code. When no extra context is needed, the seed may remain and the agent discovers relevant standards itself.
|
||||
7. After every important conclusion, immediately update the owning artifact so that it does not live only in the conversation.
|
||||
8. Do not use `trellis-brainstorm`. Leave open decisions and TDD seams for item-by-item review with `grill-with-docs` in step 1.3.
|
||||
|
||||
At minimum, `prd.md` contains: Goal, Background/Evidence, In Scope, Out of Scope, Requirements, Acceptance Criteria, Constraints, Open Decisions, and Testing Strategy.
|
||||
|
||||
Before finishing, perform one convergence pass: remove duplicate facts and resolved questions while preserving every evidence anchor, constraint, decision, and acceptance mapping.
|
||||
|
||||
#### 1.2 Research / prototype / design inquiry `[optional · repeatable]`
|
||||
|
||||
Research only when the repository cannot directly answer a technical fact. Prototype only when a state model, business rule, or UI must be run or observed to make a decision. Choose the corresponding design method when the interface, seam, domain vocabulary, or architectural shape is itself the question.
|
||||
|
||||
Research rules:
|
||||
|
||||
- Prefer official documentation, standards, source code, and first-party APIs;
|
||||
- Use the current-documentation tool required by the project `AGENTS.md`;
|
||||
- For a Trellis task, write conclusions that affect implementation to `{TASK_DIR}/research/<topic>.md`;
|
||||
- Record sources, version/date, conclusions, scope of applicability, and unresolved risks;
|
||||
- Research supplies evidence; it does not make product decisions on behalf of the user.
|
||||
|
||||
Prototype rule: treat prototype code as throwaway from the beginning. Keep the answer, but do not merge the prototype into the product implementation without redesigning it.
|
||||
|
||||
#### 1.3 Review spec with `grill-with-docs` `[required · once]`
|
||||
|
||||
Explicitly load `grill-with-docs` and use it to review `prd.md` plus conditional `design.md` and `implement.md`:
|
||||
|
||||
1. Answer factual questions from environmental evidence first. Do not ask the user for facts that can be found in the repository.
|
||||
2. Grill product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
|
||||
3. Ask one question at a time. Each question includes a recommended answer and the tradeoffs of alternative choices.
|
||||
4. After each answer is confirmed, immediately synchronize it to the owning Trellis artifact.
|
||||
5. When `Implementation Mode: tdd`, use the `/tdd` contract to confirm the public interface/seam to observe. Do not write tests or enter Phase 2 before confirmation. Do not ask about TDD seams in `standard` mode.
|
||||
6. `CONTEXT.md` records only durable domain terminology. An ADR records only a decision that is hard to reverse, counterintuitive, and based on a real tradeoff.
|
||||
7. Trellis artifacts remain the source of truth for the current task spec. Do not duplicate task details in the glossary or ADRs.
|
||||
|
||||
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`.
|
||||
|
||||
This step is complete when the user confirms shared understanding. That confirmation completes the spec review; do not add another Trellis implementation-approval layer.
|
||||
|
||||
#### 1.4 Activate or stop at planning boundary `[required · once]`
|
||||
|
||||
Apply the authorization matrix:
|
||||
|
||||
| Situation | Action |
|
||||
| --- | --- |
|
||||
| The user explicitly requested implement/build/fix/change; artifacts are ready; no user decision remains open | Run `task.py start` and enter Phase 2 without asking again |
|
||||
| The user requested only plan/spec/review/diagnose | Stop at the authorization boundary; deliver the requested artifact or continue read-only execution without modifying product code |
|
||||
| The selected skill has an explicit human gate | Follow that gate |
|
||||
| The action involves external writes, destructive actions, payment, permissions, or material scope expansion | Confirm that action first |
|
||||
| The artifacts materially changed scope and the original authorization no longer covers it | Request direction first |
|
||||
|
||||
Start command:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
```
|
||||
|
||||
The original implementation request plus the shared-understanding confirmation in step 1.3 constitutes implementation authorization. Do not add another Trellis planning approval.
|
||||
|
||||
For a planning-only task, the planning artifacts are themselves the deliverable. Once completed and verified, the task may go directly to archive in step 3.5 without being moved to `in_progress` merely for formality.
|
||||
|
||||
#### 1.5 Planning completion criteria
|
||||
|
||||
| Condition | Required |
|
||||
| --- | :---: |
|
||||
| `prd.md` contains observable acceptance criteria | ✅ |
|
||||
| Repository-answerable facts have evidence | ✅ |
|
||||
| No blocking user decision remains | ✅ |
|
||||
| `design.md` exists when its conditions apply | ✅ |
|
||||
| `implement.md` exists with a checkpoint when its conditions apply | ✅ |
|
||||
| Research conclusions have been persisted, if any | ✅ |
|
||||
| `Testing Strategy` records `standard` or `tdd` | ✅ |
|
||||
| Public test seams have been confirmed by the user in `tdd` mode | Conditional ✅ |
|
||||
| `grill-with-docs` review reached shared understanding | ✅ |
|
||||
| The current action remains within user authorization | ✅ |
|
||||
|
||||
## Phase 2: Execute
|
||||
|
||||
Goal: complete the authorized work through one explicit method and leave auditable evidence.
|
||||
|
||||
#### 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
|
||||
|
||||
Before execution:
|
||||
|
||||
1. Read `prd.md`, conditional `design.md` / `implement.md`, and relevant research.
|
||||
2. Run package/spec discovery and read the pre-development checklist and concrete standards for the affected area.
|
||||
3. Check `git status` and distinguish task changes, existing user changes, and unrelated parallel work.
|
||||
4. If the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by project `AGENTS.md`.
|
||||
5. Read `Testing Strategy` and accept only `standard` or `tdd`. If `tdd` has no confirmed seam, return to step 1.3; never select or infer TDD in Phase 2.
|
||||
6. Use `task.py current --source` to obtain the exact task path for the current session and confirm that the task matches the request and has `in_progress` status.
|
||||
7. Dispatch one `trellis-matt-implement`; never dispatch the native `trellis-implement`. The prompt must include the exact task path, mode, and seams:
|
||||
|
||||
```text
|
||||
Active task: <task-path>
|
||||
Implementation mode: <standard | tdd>
|
||||
Confirmed TDD seams:
|
||||
- <public seam, or Not applicable>
|
||||
Implement only <delegated slice> from the reviewed task artifacts.
|
||||
Do not change task state, dispatch another agent, or perform Git writes.
|
||||
```
|
||||
|
||||
Agent contract:
|
||||
|
||||
- `trellis-matt-implement` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each slice selects exactly one implementation method;
|
||||
- Read context in this order: real `implement.jsonl` entries → `prd.md` → conditional `design.md` → conditional `implement.md` → relevant project standards;
|
||||
- Treat the reviewed Trellis artifacts as the spec/tickets and make only the minimum sufficient implementation for the delegated slice;
|
||||
- Do not overwrite, revert, or commit the user's existing changes;
|
||||
- Follow project comment conventions for public functions, classes, and complex logic, explaining design rationale and critical boundaries;
|
||||
- `standard`: do not use TDD/test-first; complete a stable implementation increment before narrow checks, then add acceptance/regression tests as needed after the behavior exists;
|
||||
- `tdd`: explicitly load `/tdd` and work only at confirmed public seams in vertical slices of one failing behavioral test → minimum green implementation; if the skill is unavailable or a seam is missing, return `blocked` without silently degrading;
|
||||
- Do not perform unrelated refactoring inside the TDD red → green loop; return candidates to the main session for review in step 2.2;
|
||||
- In both modes, run all applicable full-scope verification at the end of the slice;
|
||||
- Do not change task state, requirements, scope, or acceptance criteria; perform Git writes; or dispatch another agent;
|
||||
- Self-review the complete delegated slice and return the implementation mode, confirmed seams, changed files, acceptance mapping, actual verification results, and remaining risks.
|
||||
|
||||
After the agent returns, the main session must inspect its report and the complete diff, then synchronize completed steps, verification evidence, next action, and blockers to the `implement.md` Current Checkpoint before entering step 2.2. A diagnosis-only or review-only task must not dispatch the implementation agent or modify product code as a convenience.
|
||||
|
||||
If the custom agent is unavailable, cannot obtain task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt fallback for `standard`, or explicitly load `/tdd` for `tdd`. Dispatch only one implementation agent by default; parallel execution is allowed only for independent child tasks or completely disjoint write scopes. Any commit still requires an explicit user request before entering step 3.4.
|
||||
|
||||
#### 2.2 Quality and acceptance check `[required · repeatable]`
|
||||
|
||||
The checking behavior depends on user intent:
|
||||
|
||||
- Implementation/fix task: fix in-scope issues found by checks, then rerun verification.
|
||||
- Review-only: report findings without modifying code.
|
||||
- Diagnosis-only: report the root cause, evidence, and recommendation without implementing a fix.
|
||||
|
||||
Every pass checks at least:
|
||||
|
||||
1. A mapping from the diff to each `prd.md` acceptance criterion;
|
||||
2. Applicable `.trellis/spec/` and project standards;
|
||||
3. Real acceptance commands for the affected area, such as lint, type-check, tests, build, or other checks;
|
||||
4. Cross-layer data flow, types, error propagation, compatibility, and regression impact when applicable;
|
||||
5. Checks not run and the reason.
|
||||
|
||||
The final pass must cover the entire task diff, not only the last patch. Record commands, exit results, and key output. When a tool was not actually run, record only `not run` or `blocked`, never `passed`.
|
||||
|
||||
When implementation mode is `tdd`, refactoring occurs only in this review stage. Rerun affected behavioral tests and all applicable full-scope verification afterward to ensure the green state remains intact.
|
||||
|
||||
If the selected review skill explicitly requires several independent review agents, that parallelism is an internal step of the Matt implementation method. If no skill matches or it cannot cover the current uncommitted diff, the main session directly reviews the complete diff. Do not stack `trellis-check` merely for formality.
|
||||
|
||||
#### 2.3 Roll back to the right phase `[on demand]`
|
||||
|
||||
- New evidence shows a requirement or acceptance criterion is wrong → return to Phase 1 and update `prd.md`.
|
||||
- The interface, compatibility, migration, or architectural shape is wrong → return to Phase 1 and update `design.md` and `implement.md`.
|
||||
- A technical fact is missing → return to research in step 1.2 and persist the conclusion.
|
||||
- The implementation drifted but the requirements remain correct → revert or correct only changes made by this task, then repeat step 2.1.
|
||||
- Never use destructive Git commands to clean the worktree or revert user changes whose ownership is uncertain.
|
||||
|
||||
## Phase 3: Finish
|
||||
|
||||
Goal: close the deliverable with evidence while keeping task records, knowledge promotion, and version control as three separate actions.
|
||||
|
||||
#### 3.2 Debug retrospective `[on demand]`
|
||||
|
||||
Run a retrospective only after repeated failures, multiple fixes for the same issue, an expensive detour, or difficulty establishing a feedback loop. Select the best-matched current diagnosis/learning method and record:
|
||||
|
||||
- The root cause;
|
||||
- Why early approaches failed;
|
||||
- Why the final evidence is trustworthy;
|
||||
- Candidate knowledge that could prevent similar issues.
|
||||
|
||||
A routine task summary does not trigger a retrospective.
|
||||
|
||||
#### 3.3 Knowledge promotion decision `[required · once]`
|
||||
|
||||
Always decide whether any knowledge is worth promoting, but do not modify `.trellis/spec/` or a cross-project knowledge base by default.
|
||||
|
||||
Candidate knowledge may be promoted only when all of the following are true:
|
||||
|
||||
1. Durable: it is not a one-off implementation detail or temporary workaround;
|
||||
2. Reusable: future tasks would take a different and better action because of it;
|
||||
3. Verified: supported by code, tests, documentation, or repeated evidence;
|
||||
4. User-confirmed: the user explicitly agrees to promote it into a spec, skill, hook, test, script, or cross-project pattern.
|
||||
|
||||
Without confirmation:
|
||||
|
||||
- It may remain in the current task's design, research, or retrospective;
|
||||
- It may be listed as a promotion candidate in the final response;
|
||||
- It must not be written automatically to `.trellis/spec/` or a canonical area of the personal knowledge base.
|
||||
|
||||
After the user confirms, use the currently available spec/compound-learning method and verify that the new rule matches current repository facts.
|
||||
|
||||
#### 3.4 Version-control actions `[on explicit request]`
|
||||
|
||||
Skip all Git write operations by default. Perform each action only when the user explicitly requests it:
|
||||
|
||||
- Commit: include only known changes from the current task; inspect dirty state and recent history first; group by logical unit; default message is `<type>(scope): <Chinese verb phrase>` with no trailing period; do not amend.
|
||||
- Push: perform only when the user explicitly requests a push. Commit authorization does not include push.
|
||||
- PR: create only when explicitly requested. Commit or push authorization does not include a PR.
|
||||
|
||||
Trellis never automatically commits a task archive or journal. The commands in section 3.5 always use `--no-commit` explicitly.
|
||||
|
||||
#### 3.5 Archive, journal and report `[required · once]`
|
||||
|
||||
First determine whether the task is genuinely complete: acceptance criteria are satisfied, required checks have direct evidence, and no blocker remains. Otherwise, update only the checkpoint and risks; do not archive.
|
||||
|
||||
Archive after completion:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
|
||||
```
|
||||
|
||||
Record the session:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "<title>" \
|
||||
--summary "<outcome, verification, remaining risk>" \
|
||||
--no-commit
|
||||
```
|
||||
|
||||
Command-level `--no-commit` ensures that both commands only write files and never stage, commit, or push, so `.trellis/config.yaml` does not need to change. Pass `--commit "<hashes>"` only when this task has already created a work commit at the user's explicit request. Otherwise omit the argument; never fabricate a hash.
|
||||
|
||||
The final response leads with the conclusion and keeps only:
|
||||
|
||||
1. Outcome;
|
||||
2. Key evidence / changed files;
|
||||
3. Verification actually run;
|
||||
4. Remaining risks or blockers;
|
||||
5. Necessary next step, only when one is genuinely needed.
|
||||
|
||||
Without direct verification evidence, do not write “complete,” “passing,” “ready to commit,” or “ready to merge.”
|
||||
|
||||
## Active Task Routing
|
||||
|
||||
When an active task exists, first read `task.json`, its artifacts, and Current Checkpoint, then resume by state:
|
||||
|
||||
| Status / evidence | Resume action |
|
||||
| --- | --- |
|
||||
| `planning`, `prd.md` has not converged | 1.1 |
|
||||
| `planning`, technical unknowns remain | 1.2 |
|
||||
| `planning`, artifacts have not passed `grill-with-docs` review | 1.3 |
|
||||
| `planning`, shared understanding has been confirmed | 1.4; start or stop at the planning boundary according to the user's original intent |
|
||||
| `in_progress`, checkpoint points to unfinished implementation/diagnosis/review | 2.1 |
|
||||
| `in_progress`, execution is complete but full-scope evidence is missing | 2.2 |
|
||||
| `in_progress`, acceptance has been verified | 3.3 → conditional 3.4 → 3.5 |
|
||||
| `completed` can still be resolved | 3.5 report; the active pointer is normally cleared after a successful archive |
|
||||
|
||||
When the user asks an unrelated simple question while a task is active, answer it Inline without modifying the task. When the user explicitly switches to another durable piece of work, save the current checkpoint before activating the new task. Do not mix two requests into one task.
|
||||
|
||||
## Runtime and Customization Invariants
|
||||
|
||||
1. `.trellis/workflow.md` is the source of truth for workflow semantics and breadcrumb text.
|
||||
2. When required steps change, update the corresponding `[workflow-state:*]` block.
|
||||
3. The status in opening and closing workflow-state tags must match exactly. Status values use only `[A-Za-z0-9_-]+`.
|
||||
4. Do not add custom task statuses unless the status writer, breadcrumb, and this document's `Active Task Routing` are updated together.
|
||||
5. This workflow retains the existing Trellis phase and step numbers to reduce drift in `get_context.py --mode phase --step <X.Y>` and platform entry files.
|
||||
6. If a bundled skill or command conflicts with this document, user instructions, `AGENTS.md`, and this document take precedence. Use the low-level Trellis commands given here without modifying bundled files.
|
||||
7. After `trellis update`, inspect `.new` sidecars or template conflicts. Never overwrite personal customizations directly.
|
||||
8. Keep breadcrumbs short. Detailed rules belong in the phase body. Keep the Phase Index and detailed phases synchronized.
|
||||
9. `agents/codex/trellis-matt-implement.toml` is the shared source of truth for the custom implementation agent; install it in a project as `.codex/agents/trellis-matt-implement.toml`.
|
||||
10. The agent relies on the exact `Active task:` path in its dispatch prompt for pull-based context loading; this setup does not require adding the new name to a Codex hook matcher.
|
||||
11. Implementation mode is limited to `standard` / `tdd`. `tdd` requires both a user trigger and confirmed public seam; the agent never upgrades modes on its own.
|
||||
|
||||
## Adoption Checklist
|
||||
|
||||
- [ ] Use this file as the project's `.trellis/workflow.md`.
|
||||
- [ ] Use the companion guide as the global or project `AGENTS.md`.
|
||||
- [ ] Copy `agents/codex/trellis-matt-implement.toml` to the project's `.codex/agents/trellis-matt-implement.toml`.
|
||||
- [ ] Verify the Codex breadcrumb in no-task, planning, and in-progress states.
|
||||
- [ ] In a `standard` test task, verify that the agent does not use TDD and reads artifacts through `Active task:`.
|
||||
- [ ] In a `tdd` test task, verify that the agent loads `/tdd` and works only at confirmed seams in vertical red → green slices.
|
||||
- [ ] In both modes, verify that the agent performs no task-lifecycle or Git write operations.
|
||||
- [ ] Verify that output from `task.py archive` and `add_session.py` contains evidence that stage/commit was skipped.
|
||||
- [ ] Use the next user message to verify the breadcrumb; open a new session to verify that the phase body and Skill Routing take effect.
|
||||
@@ -0,0 +1,127 @@
|
||||
name = "trellis-matt-implement"
|
||||
description = "Trellis task implementer that follows reviewed artifacts in explicit standard or TDD mode without task-lifecycle or Git writes."
|
||||
sandbox_mode = "workspace-write"
|
||||
|
||||
developer_instructions = """
|
||||
You are the `trellis-matt-implement` sub-agent. The main session owns the
|
||||
Trellis lifecycle, scope, user communication, final acceptance, and every
|
||||
version-control action. You own only the delegated implementation slice.
|
||||
|
||||
## Recursion and ownership guard
|
||||
|
||||
- Do not spawn another implementation, check, review, or research sub-agent.
|
||||
- Do not call a Matt `/implement` wrapper. This prompt is the workflow-approved,
|
||||
adapted implementation contract. In explicit TDD mode, load `/tdd` instead.
|
||||
- Do not create, start, finish, archive, or switch Trellis tasks.
|
||||
- Do not change `task.json`, task status, requirements, scope, or acceptance
|
||||
criteria. Report any needed decision to the main session.
|
||||
- Do not run Git write operations, including add, commit, push, merge, rebase,
|
||||
reset, checkout, restore, stash, or clean. Read-only Git inspection is allowed.
|
||||
|
||||
## Task context protocol
|
||||
|
||||
The dispatch prompt must begin with:
|
||||
|
||||
`Active task: <task-path>`
|
||||
|
||||
The dispatch prompt should then declare one implementation mode:
|
||||
|
||||
`Implementation mode: standard | tdd`
|
||||
|
||||
For `tdd`, it must also list at least one user-confirmed public seam under:
|
||||
|
||||
`Confirmed TDD seams:`
|
||||
|
||||
If the `Active task:` line is missing or its directory does not exist, stop and
|
||||
ask the main session for the exact path. Do not guess, run `task.py current`, or
|
||||
borrow another session's task.
|
||||
|
||||
If the implementation mode is missing, use `standard`. Never infer `tdd` from
|
||||
risk, test coverage, or implementation complexity. If mode is `tdd` but no
|
||||
confirmed seam is supplied or persisted in the reviewed task artifacts, stop
|
||||
before writing and report the missing decision to the main session.
|
||||
|
||||
Before writing code, read context in this order:
|
||||
|
||||
1. `<task-path>/implement.jsonl` if present. Read every real file or directory
|
||||
entry and ignore seed/example rows without a `file` or `path`.
|
||||
2. `<task-path>/prd.md`.
|
||||
3. `<task-path>/design.md` if present.
|
||||
4. `<task-path>/implement.md` if present.
|
||||
5. Relevant `.trellis/spec/` guidance and repository-local instructions for the
|
||||
affected code.
|
||||
|
||||
If `implement.jsonl` is missing or contains only a seed row, continue from the
|
||||
task artifacts and discover the narrowest relevant project specs yourself.
|
||||
|
||||
## Common implementation method
|
||||
|
||||
1. Confirm that the delegated slice maps to reviewed requirements and observable
|
||||
acceptance criteria. Surface ambiguity instead of inventing a product or
|
||||
scope decision.
|
||||
2. Inspect existing code, tests, configuration, and repository state before
|
||||
editing. Preserve user changes and unrelated parallel work.
|
||||
3. Execute exactly one of the mode contracts below. Do not blend both modes in
|
||||
the same delegated slice unless the main session updates the reviewed plan.
|
||||
4. At the end of the delegated slice, run all applicable full-scope validation
|
||||
that can be completed safely in the current environment.
|
||||
5. Self-review the complete slice diff against the task artifacts and relevant
|
||||
specs. Fix in-scope issues directly, rerun affected checks, and leave final
|
||||
cross-task acceptance to the main session.
|
||||
|
||||
### Standard mode
|
||||
|
||||
1. Make the minimum sufficient, coherent implementation increment that follows
|
||||
existing patterns and project standards.
|
||||
2. Do not use TDD or test-first development in this mode. After each stable
|
||||
implementation increment, run narrow feedback such as the relevant test
|
||||
file, affected type-check, or focused lint command.
|
||||
3. Add or update tests when needed for acceptance evidence, regression
|
||||
protection, or high-risk logic, after the corresponding implementation
|
||||
behavior exists.
|
||||
|
||||
### TDD mode
|
||||
|
||||
1. Explicitly load and follow the available `/tdd` skill. If it cannot be
|
||||
loaded, stop before writing and report `blocked` so the main session can run
|
||||
the TDD fallback; do not silently improvise a different process.
|
||||
2. Test only through the confirmed public seams. Do not add tests at a new or
|
||||
internal seam without returning the decision to the main session.
|
||||
3. Work in vertical red → green slices: one failing behavioral test, then only
|
||||
enough implementation to pass it, then repeat.
|
||||
4. Do not perform unrelated refactoring inside the red → green loop. Record
|
||||
refactoring candidates for the main session's review stage.
|
||||
|
||||
Follow repository documentation-comment rules for functions, classes, and
|
||||
complex logic. Comments explain design rationale and critical boundaries rather
|
||||
than restating the code.
|
||||
|
||||
## Completion report
|
||||
|
||||
Return a concise report using this shape:
|
||||
|
||||
## Implementation Result
|
||||
|
||||
### Implementation Mode
|
||||
- `standard | tdd`
|
||||
- Confirmed TDD seams: <list, or "Not applicable">
|
||||
|
||||
### Outcome
|
||||
- <what was implemented>
|
||||
|
||||
### Files Changed
|
||||
- `<path>` — <reason>
|
||||
|
||||
### Acceptance Mapping
|
||||
- <criterion> — <evidence>
|
||||
|
||||
### Verification
|
||||
- `<command>` — <exit result and key evidence>
|
||||
- Not run / blocked checks — <reason>
|
||||
|
||||
### Remaining Risks or Decisions
|
||||
- <item, or "None">
|
||||
|
||||
Do not claim completion or passing checks without direct evidence. Do not commit
|
||||
or suggest that a commit was created.
|
||||
"""
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
id: INTAKE-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: intake
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids: []
|
||||
derived_ids:
|
||||
- UR-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 原始输入：AI 研发工作流
|
||||
|
||||
## 背景
|
||||
|
||||
希望在当前 vault 中开始研究 AI 研发工作流，方向是 `spec + skill` 双驱动。
|
||||
|
||||
## 原始描述
|
||||
|
||||
每个需求由多个文档关联起来，从开始输入到后续逐项产出都能追踪。阶段包括用户需求、研发需求、详细设计、编码、测试。
|
||||
|
||||
## 期望结果
|
||||
|
||||
逐步完成相关 skill 和规范说明，支持长期迭代和调优。
|
||||
|
||||
## 待确认问题
|
||||
|
||||
- OR、DR、DS 的最终命名和字段是否需要贴合现有公司标准。
|
||||
- 每个阶段是否需要正式审批人和审批记录。
|
||||
- 是否需要自动化脚本检查追踪关系。
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
id: RA-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: requirement-analysis
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-20260629-001
|
||||
derived_ids:
|
||||
- OR-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 需求分析：AI 研发工作流研究区
|
||||
|
||||
## 问题拆解
|
||||
|
||||
- 需求链路容易断裂，需要统一 artifact 模型。
|
||||
- skill 容易散落，需要独立源目录。
|
||||
- 真实需求和规范资产容易混淆，需要分层目录。
|
||||
|
||||
## 约束
|
||||
|
||||
- 当前阶段以 vault 内 Markdown 为主。
|
||||
- 不要求一次完成所有 skill。
|
||||
- 需要支持后续反复调优。
|
||||
|
||||
## 风险
|
||||
|
||||
- 过早细化字段会导致维护成本高。
|
||||
- skill 如果直接做成正式安装版，迭代成本会变高。
|
||||
|
||||
## 决策点
|
||||
|
||||
- 先用本目录维护 skill 草稿，稳定后再安装到 Codex skill 目录。
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
id: SA-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: scenario-analysis
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- UR-20260629-001
|
||||
- RA-20260629-001
|
||||
derived_ids:
|
||||
- OR-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 场景分析：AI 研发工作流研究区
|
||||
|
||||
## 主场景
|
||||
|
||||
用户提出一个新需求后，在 `50-cases/` 下创建 case，并按阶段生成 UR、RA、SA、OR、DR、DS、TASK、TP、TC。
|
||||
|
||||
## 替代场景
|
||||
|
||||
用户只想打磨某一个 skill，则在 `20-skills/` 中修改草稿，并用 `60-evaluations/` 中的评测样本验证。
|
||||
|
||||
## 异常场景
|
||||
|
||||
如果某个下游产物找不到上游来源，则需要在追踪矩阵中标记为 `missing` 或补齐 `source_ids`。
|
||||
|
||||
## 边界场景
|
||||
|
||||
如果只是零散想法，还不进入正式 case，可以先放入现有 `AI Coding/inbox/`，成熟后再转入本工作区。
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
id: UR-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: user-requirement
|
||||
stage: user-requirement
|
||||
owner_role: PM
|
||||
status: draft
|
||||
source_ids:
|
||||
- INTAKE-20260629-001
|
||||
derived_ids:
|
||||
- RA-20260629-001
|
||||
- SA-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 用户需求：建立 AI 研发工作流研究区
|
||||
|
||||
## 一句话需求
|
||||
|
||||
作为 AI 研发工作流研究者，我希望建立一套可长期迭代的目录、规范、模板和 skill 草稿，以便逐步沉淀从需求到测试的完整链路。
|
||||
|
||||
## 用户目标
|
||||
|
||||
- 能按阶段组织需求产物。
|
||||
- 能追踪每个需求从输入到最终测试的链路。
|
||||
- 能逐步调优 PM、SE、RD、测试侧 skill。
|
||||
|
||||
## 业务价值
|
||||
|
||||
降低 AI 参与研发时的上下文断裂，提高需求、设计、编码、测试之间的一致性。
|
||||
|
||||
## 范围
|
||||
|
||||
### 包含
|
||||
|
||||
- 目录结构。
|
||||
- 初始规范。
|
||||
- 初始模板。
|
||||
- 初始 skill 草稿。
|
||||
- 示例 case。
|
||||
|
||||
### 不包含
|
||||
|
||||
- 一次性完成所有正式 skill。
|
||||
- 直接接入外部项目管理系统。
|
||||
|
||||
## 验收方向
|
||||
|
||||
能在 vault 中看到完整骨架，并能基于示例 case 继续完善下一阶段产物。
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: DR-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: development-requirement
|
||||
stage: development-requirement
|
||||
owner_role: SE
|
||||
status: draft
|
||||
source_ids:
|
||||
- OR-20260629-001
|
||||
derived_ids:
|
||||
- DS-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# DR：研发需求
|
||||
|
||||
## 功能需求
|
||||
|
||||
- 创建长期研究目录。
|
||||
- 创建标准文档。
|
||||
- 创建模板文档。
|
||||
- 创建 skill 草稿。
|
||||
- 创建示例 case。
|
||||
|
||||
## 非功能需求
|
||||
|
||||
- 文档应便于 Obsidian 浏览。
|
||||
- 结构应支持长期迭代。
|
||||
- skill 草稿应尽量接近 Codex skill 格式。
|
||||
|
||||
## 数据需求
|
||||
|
||||
- 每个 artifact 使用 frontmatter 维护追踪字段。
|
||||
|
||||
## 兼容性
|
||||
|
||||
- 不破坏 `AI Coding` 现有目录。
|
||||
- 不要求立即安装到 Codex skill 目录。
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: OR-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: objective-requirement
|
||||
stage: development-requirement
|
||||
owner_role: SE
|
||||
status: draft
|
||||
source_ids:
|
||||
- RA-20260629-001
|
||||
- SA-20260629-001
|
||||
derived_ids:
|
||||
- DR-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# OR：研发目标需求
|
||||
|
||||
## 工程目标
|
||||
|
||||
在 vault 中建立一个可长期演化的 AI 研发工作流知识区，并支持需求链路追踪。
|
||||
|
||||
## 交付范围
|
||||
|
||||
- 目录结构。
|
||||
- 元模型规范。
|
||||
- 生命周期和追踪规范。
|
||||
- 模板。
|
||||
- skill 草稿。
|
||||
- 示例 case。
|
||||
|
||||
## 成功标准
|
||||
|
||||
- 所有核心目录存在。
|
||||
- 核心文档可被用户继续编辑。
|
||||
- 示例 case 能表达从 INTAKE 到 TC 的链路。
|
||||
|
||||
## 风险
|
||||
|
||||
- 当前 OR/DR/DS 定义是初始约定，后续可能按用户习惯调整。
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
id: DS-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: design-specification
|
||||
stage: detailed-design
|
||||
owner_role: RD
|
||||
status: draft
|
||||
source_ids:
|
||||
- OR-20260629-001
|
||||
- DR-20260629-001
|
||||
derived_ids:
|
||||
- TASK-20260629-001
|
||||
- TP-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# DS：详细设计
|
||||
|
||||
## 影响范围
|
||||
|
||||
新增 `AI Coding/AI-RD-Workflow/`，不修改现有文件。
|
||||
|
||||
## 模块拆分
|
||||
|
||||
- `00-meta`：元信息。
|
||||
- `10-standards`：规范。
|
||||
- `20-skills`：skill 草稿。
|
||||
- `30-templates`：模板。
|
||||
- `40-workflows`：工作流。
|
||||
- `50-cases`：需求实例。
|
||||
- `60-evaluations`：评测。
|
||||
- `90-archive`：归档。
|
||||
|
||||
## 开发任务拆分
|
||||
|
||||
- TASK-20260629-001：创建目录和初始文档。
|
||||
|
||||
## 测试点
|
||||
|
||||
- 检查目录是否存在。
|
||||
- 检查关键文档是否存在。
|
||||
- 检查示例 case 是否有完整追踪链路。
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: TASK-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: implementation-task
|
||||
stage: implementation
|
||||
owner_role: RD
|
||||
status: draft
|
||||
source_ids:
|
||||
- DS-20260629-001
|
||||
derived_ids: []
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# TASK：创建目录和初始文档
|
||||
|
||||
## 目标
|
||||
|
||||
创建 AI 研发工作流研究区的第一版骨架。
|
||||
|
||||
## 文件范围
|
||||
|
||||
- `AI Coding/AI-RD-Workflow/`
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 目录存在。
|
||||
- 核心规范和模板存在。
|
||||
- 示例 case 存在。
|
||||
- 追踪矩阵存在。
|
||||
|
||||
## 验证方式
|
||||
|
||||
使用 `find` 检查目录和文件结构。
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
id: TC-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: test-case
|
||||
stage: test
|
||||
owner_role: QA
|
||||
status: draft
|
||||
source_ids:
|
||||
- TP-20260629-001
|
||||
derived_ids: []
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 测试用例：目录骨架
|
||||
|
||||
| 用例 ID | 类型 | 来源 ID | 前置条件 | 步骤 | 预期结果 | 优先级 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| TC-20260629-001-01 | positive | DS-20260629-001 | vault 可访问 | 枚举 `AI Coding/AI-RD-Workflow/` | 核心目录存在 | P0 |
|
||||
| TC-20260629-001-02 | positive | DS-20260629-001 | 文件已创建 | 检查 `50-cases/REQ-20260629-001-example/traceability.md` | 能看到从 INTAKE 到 TC 的链路 | P0 |
|
||||
| TC-20260629-001-03 | boundary | DR-20260629-001 | 已有 `AI Coding` 内容 | 检查现有目录 | 现有文件未被修改 | P1 |
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
id: TP-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: test-plan
|
||||
stage: test
|
||||
owner_role: QA
|
||||
status: draft
|
||||
source_ids:
|
||||
- DS-20260629-001
|
||||
derived_ids:
|
||||
- TC-20260629-001
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 测试计划：目录骨架
|
||||
|
||||
## 测试范围
|
||||
|
||||
- 目录结构。
|
||||
- 核心文档。
|
||||
- 示例 case 追踪链路。
|
||||
|
||||
## 测试策略
|
||||
|
||||
通过文件枚举检查结构，通过人工阅读检查文档是否可继续迭代。
|
||||
|
||||
## 准出条件
|
||||
|
||||
- 关键目录和文件存在。
|
||||
- 示例 case 中每个阶段至少有一个 artifact。
|
||||
- `traceability.md` 能表达上游和下游关系。
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
id: TRACE-REQ-20260629-001
|
||||
case_id: REQ-20260629-001-example
|
||||
type: traceability-matrix
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
updated: 2026-06-29
|
||||
---
|
||||
|
||||
# 追踪矩阵
|
||||
|
||||
| 上游 ID | 下游 ID | 关系 | 覆盖状态 | 备注 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| INTAKE-20260629-001 | UR-20260629-001 | derives | covered | 原始输入转用户需求 |
|
||||
| UR-20260629-001 | RA-20260629-001 | analyzes | covered | 用户需求分析 |
|
||||
| UR-20260629-001 | SA-20260629-001 | scenarios | covered | 场景分析 |
|
||||
| RA-20260629-001 | OR-20260629-001 | translates | partial | 待补 SE 细化 |
|
||||
| SA-20260629-001 | OR-20260629-001 | translates | partial | 待补 SE 细化 |
|
||||
| OR-20260629-001 | DR-20260629-001 | details | partial | 待补工程要求 |
|
||||
| DR-20260629-001 | DS-20260629-001 | designs | partial | 待补详细设计 |
|
||||
| DS-20260629-001 | TASK-20260629-001 | implements | partial | 待补任务拆分 |
|
||||
| DS-20260629-001 | TP-20260629-001 | tests | partial | 待补测试计划 |
|
||||
| TP-20260629-001 | TC-20260629-001 | cases | partial | 待补测试用例 |
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: PROMPT-RUNS-INDEX
|
||||
type: evaluation-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# Prompt Runs
|
||||
|
||||
记录重要 prompt 运行过程、输入、输出、问题和结论。
|
||||
|
||||
建议字段：
|
||||
|
||||
- 日期。
|
||||
- 使用的 skill。
|
||||
- 输入 artifact。
|
||||
- 输出 artifact。
|
||||
- 失败点。
|
||||
- 后续改进。
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: RETROSPECTIVES-INDEX
|
||||
type: evaluation-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 复盘
|
||||
|
||||
记录真实使用后的经验。
|
||||
|
||||
每次复盘关注：
|
||||
|
||||
- 哪个阶段卡住。
|
||||
- 哪个模板字段不够。
|
||||
- 哪个 skill 指令不清晰。
|
||||
- 哪个追踪关系缺失。
|
||||
- 是否需要更新标准、模板或 skill。
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
id: SKILL-EVAL-CASES-INDEX
|
||||
type: evaluation-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# Skill 评测用例
|
||||
|
||||
用于保存可重复执行的 skill 评测样本。
|
||||
|
||||
建议结构：
|
||||
|
||||
```text
|
||||
skill-eval-cases/
|
||||
├── pm-requirement-review/
|
||||
├── pm-requirement-refine/
|
||||
├── se-requirement-review/
|
||||
├── se-requirement-analysis/
|
||||
├── rd-design-generate/
|
||||
└── test-case-generate/
|
||||
```
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
id: ARCHIVE-INDEX-AI-RD-WORKFLOW
|
||||
type: archive-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# 归档
|
||||
|
||||
存放废弃方案、历史版本和不再推荐使用的实验材料。
|
||||
|
||||
归档文件应说明：
|
||||
|
||||
- 归档原因。
|
||||
- 替代方案。
|
||||
- 归档日期。
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
id: AI-RD-WORKFLOW
|
||||
type: workspace-index
|
||||
status: draft
|
||||
created: 2026-06-29
|
||||
---
|
||||
|
||||
# AI 研发工作流
|
||||
|
||||
目标：建设一套 `spec + skill` 双驱动的 AI 研发工作流，让每个需求从原始输入到需求分析、研发需求、详细设计、编码、测试都能被追踪、复用和迭代。
|
||||
|
||||
## 目录
|
||||
|
||||
- `00-meta/`：术语、路线图、文档模型、命名规范。
|
||||
- `10-standards/`：生命周期、评审门禁、角色边界、追踪规则。
|
||||
- `20-skills/`：面向 Codex/AI agent 的 skill 源草稿。
|
||||
- `30-templates/`：各阶段文档模板。
|
||||
- `40-workflows/`：PM、SE、RD、AI 开发工作流。
|
||||
- `50-cases/`：真实或示例需求实例，每个 case 保留完整链路。
|
||||
- `60-evaluations/`：skill 评测用例、prompt run、复盘。
|
||||
- `90-archive/`：废弃或历史版本资料。
|
||||
|
||||
## 迭代原则
|
||||
|
||||
1. 先稳定文档关系，再扩展具体模板字段。
|
||||
2. 每个 skill 先以草稿方式在本目录维护，稳定后再安装到 `$CODEX_HOME/skills` 或 `~/.codex/skills`。
|
||||
3. 每个真实需求都放入 `50-cases/REQ-yyyymmdd-nnn-name/`，不要把产物散落在规范目录里。
|
||||
4. 所有产物必须通过 frontmatter 记录 `id`、`case_id`、`type`、`stage`、`source_ids`、`derived_ids`。
|
||||
|
||||
## 推荐下一步
|
||||
|
||||
先完善 `00-meta/artifact-model.md` 和 `10-standards/traceability.md`，再从 `20-skills/pm-requirement-review/SKILL.md` 开始打磨第一个可用 skill。
|
||||
@@ -0,0 +1,20 @@
|
||||
多模型配置在文档里面没有明确model family key，下面是一个正确的配置：
|
||||
|
||||
|
||||
# 多模型配置
|
||||
## 默认视觉模型：Qwen3-VL
|
||||
MIDSCENE_MODEL_BASE_URL="[https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1)"
|
||||
MIDSCENE_MODEL_API_KEY="" MIDSCENE_MODEL_NAME="qwen3.5-plus"
|
||||
MIDSCENE_MODEL_FAMILY="qwen3.5" MIDSCENE_MODEL_REASONING_ENABLED="false"
|
||||
|
||||
## Planning 模型：doubao-seed-2-0-pro-260215
|
||||
MIDSCENE_PLANNING_MODEL_BASE_URL="[https://ark.cn-beijing.volces.com/api/coding/v3](https://ark.cn-beijing.volces.com/api/coding/v3) "
|
||||
MIDSCENE_PLANNING_MODEL_API_KEY=""
|
||||
MIDSCENE_PLANNING_MODEL_NAME="doubao-seed-2-0-pro-260215"
|
||||
MIDSCENE_PLANNING_MODEL_FAMILY="doubao-seed"
|
||||
|
||||
## Insight 模型：doubao-seed-2-0-pro-260215
|
||||
MIDSCENE_INSIGHT_MODEL_BASE_URL="[https://ark.cn-beijing.volces.com/api/coding/v3](https://ark.cn-beijing.volces.com/api/coding/v3)"
|
||||
MIDSCENE_INSIGHT_MODEL_API_KEY=""
|
||||
MIDSCENE_INSIGHT_MODEL_NAME="doubao-seed-2-0-pro-260215"
|
||||
MIDSCENE_INSIGHT_MODEL_FAMILY="doubao-seed"
|
||||
@@ -0,0 +1,331 @@
|
||||
# MonoProxy 订阅信息获取工作流
|
||||
|
||||
本文记录如何从 macOS 版 MonoProxy 的本地配置中获取自有账户的节点信息，并生成不包含节点密码的 Clash YAML 列表。
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 应用路径：`/Applications/MonoProxyMac.app`
|
||||
- 配置路径：`~/Library/Application Support/MonoProxy/config.json`
|
||||
- 已验证日期：2026-07-24
|
||||
- 输出字段：`name`、`server`、`port`、`type`、`cipher`、`udp`
|
||||
- 明确排除：节点 `password`、登录令牌、刷新令牌和账户信息
|
||||
|
||||
仅应处理自己拥有或获授权访问的账户与配置。不要上传或公开分享原始 `config.json`，其中还包含账户令牌和加密后的节点密码。
|
||||
|
||||
## 结论
|
||||
|
||||
MonoProxy 将节点数组保存在 `config.json` 的 `mn_service_<service-id>_servers` 字段中。该字段是 Base64 字符串，解码后的数据布局为：
|
||||
|
||||
```text
|
||||
salt（16 字节）
|
||||
+ IV（16 字节）
|
||||
+ HMAC-SHA256（32 字节）
|
||||
+ AES-256-CBC ciphertext（剩余字节）
|
||||
```
|
||||
|
||||
密钥派生参数：
|
||||
|
||||
```text
|
||||
算法：PBKDF2-HMAC-SHA256
|
||||
迭代次数：100000
|
||||
密钥长度：32 字节
|
||||
配置封装口令：MonoProxyMac.MNLocalManager.Services.v1
|
||||
```
|
||||
|
||||
这里的“配置封装口令”是应用二进制中用于保护本地配置结构的固定值，不是 Shadowsocks 节点的 `password`。
|
||||
|
||||
解密流程必须先验证 HMAC，再执行 AES 解密。HMAC 不匹配时应立即停止，不能忽略校验继续处理。
|
||||
|
||||
## 步骤一：让 MonoProxy 刷新本地配置
|
||||
|
||||
1. 启动 MonoProxy 并登录自己的账户。
|
||||
2. 等待节点列表完成刷新；是否开启系统代理不影响离线读取，但刷新过程需要网络。
|
||||
3. 检查配置文件是否刚刚更新：
|
||||
|
||||
```bash
|
||||
stat -f '%N | modified=%Sm | size=%z' \
|
||||
-t '%Y-%m-%d %H:%M:%S %z' \
|
||||
"$HOME/Library/Application Support/MonoProxy/config.json"
|
||||
```
|
||||
|
||||
如果文件不存在，先确认应用是否已登录并成功获取服务信息。
|
||||
|
||||
## 步骤二：确认节点字段
|
||||
|
||||
只查看字段名称，不输出令牌或节点密码：
|
||||
|
||||
```bash
|
||||
jq -r 'keys[] | select(test("^mn_service_.*_servers$"))' \
|
||||
"$HOME/Library/Application Support/MonoProxy/config.json"
|
||||
```
|
||||
|
||||
正常情况下会得到类似：
|
||||
|
||||
```text
|
||||
mn_service_2462_servers
|
||||
```
|
||||
|
||||
服务 ID 可能随账户或后端迁移而变化，因此提取脚本不应硬编码数字部分。
|
||||
|
||||
## 步骤三：使用离线脚本生成无密码 YAML
|
||||
|
||||
下面的脚本仅使用 Node.js 内置的 `fs` 和 `crypto` 模块，不需要安装第三方依赖，也不会联网。脚本会：
|
||||
|
||||
1. 自动查找 `mn_service_<id>_servers` 字段；
|
||||
2. Base64 解码数据；
|
||||
3. 使用 PBKDF2-SHA256 派生密钥；
|
||||
4. 验证 HMAC-SHA256；
|
||||
5. 使用 AES-256-CBC 解密节点 JSON；
|
||||
6. 输出不含 `password` 的 Clash YAML。
|
||||
|
||||
保存为 `extract-monoproxy.js`：
|
||||
|
||||
```javascript
|
||||
const fs = require("fs");
|
||||
const crypto = require("crypto");
|
||||
|
||||
const configPath =
|
||||
process.argv[2] ||
|
||||
`${process.env.HOME}/Library/Application Support/MonoProxy/config.json`;
|
||||
|
||||
const configEnvelopePassword =
|
||||
"MonoProxyMac.MNLocalManager.Services.v1";
|
||||
|
||||
/**
|
||||
* 使用 YAML 单引号格式转义字符串，避免节点名称中的特殊字符破坏 YAML。
|
||||
* @param {unknown} value 需要编码的值。
|
||||
* @returns {string} 可安全写入 YAML 的单引号字符串。
|
||||
*/
|
||||
function yamlString(value) {
|
||||
return `'${String(value).replaceAll("'", "''")}'`;
|
||||
}
|
||||
|
||||
const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
|
||||
const serverKey = Object.keys(config).find((key) =>
|
||||
/^mn_service_.*_servers$/.test(key),
|
||||
);
|
||||
|
||||
if (!serverKey) {
|
||||
throw new Error("未找到 mn_service_<id>_servers 字段");
|
||||
}
|
||||
|
||||
const envelope = Buffer.from(config[serverKey], "base64");
|
||||
if (envelope.length <= 64) {
|
||||
throw new Error("节点密文长度异常");
|
||||
}
|
||||
|
||||
const salt = envelope.subarray(0, 16);
|
||||
const iv = envelope.subarray(16, 32);
|
||||
const storedHmac = envelope.subarray(32, 64);
|
||||
const ciphertext = envelope.subarray(64);
|
||||
|
||||
const key = crypto.pbkdf2Sync(
|
||||
configEnvelopePassword,
|
||||
salt,
|
||||
100000,
|
||||
32,
|
||||
"sha256",
|
||||
);
|
||||
|
||||
const calculatedHmac = crypto
|
||||
.createHmac("sha256", key)
|
||||
.update(Buffer.concat([salt, iv, ciphertext]))
|
||||
.digest();
|
||||
|
||||
if (
|
||||
storedHmac.length !== calculatedHmac.length ||
|
||||
!crypto.timingSafeEqual(storedHmac, calculatedHmac)
|
||||
) {
|
||||
throw new Error(
|
||||
"HMAC 校验失败：配置可能损坏，或 MonoProxy 已更改加密格式",
|
||||
);
|
||||
}
|
||||
|
||||
const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
|
||||
const plaintext = Buffer.concat([
|
||||
decipher.update(ciphertext),
|
||||
decipher.final(),
|
||||
]).toString("utf8");
|
||||
|
||||
const nodes = JSON.parse(plaintext);
|
||||
if (!Array.isArray(nodes)) {
|
||||
throw new Error("解密结果不是节点数组");
|
||||
}
|
||||
|
||||
console.log("proxies:");
|
||||
for (const node of nodes) {
|
||||
if (!node.alias || !node.hostname || !node.port || !node.encryption) {
|
||||
throw new Error("节点缺少 alias/hostname/port/encryption 字段");
|
||||
}
|
||||
|
||||
console.log(` - name: ${yamlString(node.alias)}`);
|
||||
console.log(` server: ${yamlString(node.hostname)}`);
|
||||
console.log(` port: ${Number(node.port)}`);
|
||||
console.log(" type: ss");
|
||||
console.log(` cipher: ${yamlString(node.encryption)}`);
|
||||
console.log(" udp: true");
|
||||
}
|
||||
```
|
||||
|
||||
执行：
|
||||
|
||||
```bash
|
||||
node extract-monoproxy.js \
|
||||
"$HOME/Library/Application Support/MonoProxy/config.json" \
|
||||
> monoproxy-subscription-without-password.yaml
|
||||
```
|
||||
|
||||
检查输出中没有密码字段：
|
||||
|
||||
```bash
|
||||
rg -n 'password|access_token|refresh_token' \
|
||||
monoproxy-subscription-without-password.yaml
|
||||
```
|
||||
|
||||
正常结果应无任何输出。再检查 YAML 的节点数量：
|
||||
|
||||
```bash
|
||||
rg -c '^ - name:' monoproxy-subscription-without-password.yaml
|
||||
```
|
||||
|
||||
当前快照应输出 `15`。
|
||||
|
||||
## 字段映射
|
||||
|
||||
| MonoProxy 节点字段 | Clash YAML 字段 | 说明 |
|
||||
|---|---|---|
|
||||
| `alias` | `name` | 节点显示名称 |
|
||||
| `hostname` | `server` | 节点域名或地址 |
|
||||
| `port` | `port` | 节点端口 |
|
||||
| 服务类型 Shadowsocks | `type: ss` | `type` 不在每个节点对象中单独存储 |
|
||||
| `encryption` | `cipher` | 当前均为 `chacha20-ietf-poly1305` |
|
||||
| 未单独存储 | `udp: true` | 按现有 Clash Shadowsocks 配置补充 |
|
||||
| `password` | 不输出 | 本工作流明确排除 |
|
||||
|
||||
## 当前完整 YAML 快照（不含 password）
|
||||
|
||||
数据来自 2026-07-24 15:03:55 更新的本地 `config.json`。HMAC 校验、AES 解密及 JSON 解析均已通过。
|
||||
|
||||
```yaml
|
||||
proxies:
|
||||
- name: 'Relay-HK1'
|
||||
server: 'scott.mydarkcloud.info'
|
||||
port: 1904
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-HK2'
|
||||
server: 'andrew.mydarkcloud.info'
|
||||
port: 2004
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-HK3'
|
||||
server: 'ethan.mydarkcloud.info'
|
||||
port: 3204
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-HK4'
|
||||
server: 'lucas.mydarkcloud.info'
|
||||
port: 999
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-SG1'
|
||||
server: 'tyler.mydarkcloud.info'
|
||||
port: 2604
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-SG2'
|
||||
server: 'tyler.mydarkcloud.info'
|
||||
port: 2704
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-JP1'
|
||||
server: 'patrick.mydarkcloud.info'
|
||||
port: 1504
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-JP2'
|
||||
server: 'ava.mydarkcloud.info'
|
||||
port: 995
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-TW1'
|
||||
server: 'kevin.mydarkcloud.info'
|
||||
port: 2104
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-TW2'
|
||||
server: 'kevin.mydarkcloud.info'
|
||||
port: 2204
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-US1'
|
||||
server: 'nathan.mydarkcloud.info'
|
||||
port: 1204
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'Relay-US2'
|
||||
server: 'nathan.mydarkcloud.info'
|
||||
port: 1304
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'JP3'
|
||||
server: 'noah.mydarkcloud.info'
|
||||
port: 999
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'TW1'
|
||||
server: 'tw1.mydarkcloud.info'
|
||||
port: 999
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
- name: 'TR1'
|
||||
server: 'tr1.mydarkcloud.info'
|
||||
port: 999
|
||||
type: ss
|
||||
cipher: 'chacha20-ietf-poly1305'
|
||||
udp: true
|
||||
```
|
||||
|
||||
## 验证与故障处理
|
||||
|
||||
### HMAC 校验失败
|
||||
|
||||
不要跳过校验。常见原因：
|
||||
|
||||
- `config.json` 正在被应用写入，读取到了不完整内容；
|
||||
- MonoProxy 更新后更改了封装口令、迭代次数或加密格式；
|
||||
- 读取了其他应用或旧版本生成的配置文件。
|
||||
|
||||
先等待应用完成刷新并重新执行。如果仍失败，需要重新检查当前二进制中的：
|
||||
|
||||
- `MNLocalManager -_encryptedJSONObjectForKey:`
|
||||
- `Ctor +d:p:e:`
|
||||
- `CCKeyDerivationPBKDF` 参数
|
||||
- `AES256CBCDecryptData:key:iv:error:`
|
||||
- `HMACSHA256WithData:key:`
|
||||
|
||||
### 输出节点为空或字段缺失
|
||||
|
||||
- 确认账户仍有有效服务；
|
||||
- 确认找到的是当前 `mn_service_<id>_servers` 字段；
|
||||
- 不要把旧版 `~/Library/Preferences/com.MonoCloud.MonoProxyMac.plist` 当作最新数据源；
|
||||
- 优先以刚刷新过的 `~/Library/Application Support/MonoProxy/config.json` 为准。
|
||||
|
||||
### YAML 无法直接连接
|
||||
|
||||
本文输出刻意删除了 `password`，因此它是用于审阅、比对和更新 `server/port` 的安全快照，并不是可直接连接的完整凭据文件。需要实际连接时，应在本地私密环境中补回自己已有的密码，且不要提交到 Git 或同步到公开笔记库。
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# 接口契约规范
|
||||
|
||||
> 前端接口定义、请求封装与数据消费的规范。
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
前端接口层的职责是：
|
||||
|
||||
- 统一管理页面访问后端的请求入口
|
||||
- 为页面、Hooks、组件提供稳定、易读的调用方式
|
||||
- 隔离具体请求库、URL 拼接、参数序列化等实现细节
|
||||
- 让页面开发只关心“调用什么接口、拿到什么数据”
|
||||
|
||||
当前仓库的接口文件统一放在 `src/api/`；现阶段不要为单个页面单独创建页面私有 `api-*` 文件，除非页面内已经形成明确且稳定的局部接口簇。
|
||||
|
||||
## 设计原则
|
||||
|
||||
- 接口方法名必须表达业务意图，而不是后端实现细节
|
||||
- 一个方法只负责一个清晰的业务动作
|
||||
- 页面层拿到的是“可直接消费的数据”，不要把请求库细节泄漏到页面
|
||||
- 相同业务模块的接口按文件聚合，避免散落在多个目录
|
||||
- 优先保持新增兼容，避免随意改动已有方法签名或返回结构
|
||||
|
||||
## 接口文件规范
|
||||
|
||||
- 文件名统一以 `api-` 开头，使用横杠连接
|
||||
- 一个业务模块对应一个接口文件，例如 `api-user.ts`、`api-order.ts`
|
||||
- 文件中只写接口定义与请求调用，不写页面逻辑、组件逻辑、复杂数据转换
|
||||
- 所有接口通过 `src/api/index.ts` 统一导出
|
||||
- 优先按业务域聚合到现有 `api-*.ts`，不要为单个接口随意新建文件
|
||||
|
||||
## 方法设计规范
|
||||
|
||||
- 方法名统一使用动词开头，表达查询、创建、更新、删除等业务动作
|
||||
- 参数少且稳定时可直接传基础参数；参数较多或未来可能扩展时，统一使用对象参数
|
||||
- 返回值应尽量稳定，避免同一接口一会儿返回数组、一会儿返回对象
|
||||
- 不要让页面知道完整 URL、Header 拼装、重试策略等底层细节
|
||||
- 不要在接口方法中混入 `setState`、弹窗提示、路由跳转等 UI 副作用
|
||||
|
||||
示例：
|
||||
|
||||
```ts
|
||||
export function apiGetKnowledgeList(params: GetKnowledgeListParams) {
|
||||
return request<GetKnowledgeListResponse>({
|
||||
url: "/knowledge/list",
|
||||
method: "GET",
|
||||
params,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 参数与返回值规范
|
||||
|
||||
- 参数类型、返回值类型要明确，避免 `any`
|
||||
- 字段命名以页面业务语义为准，不要直接照搬后端数据库字段语义
|
||||
- 可选字段必须是“明确可选”，不能依赖不清晰的 `null / undefined` 约定
|
||||
- 列表、分页、详情等场景的数据结构要保持一致性
|
||||
- 如果页面需要二次加工，优先在页面侧的 Hook、组件组装层或局部工具中处理，而不是污染全局接口层
|
||||
|
||||
## 错误处理规范
|
||||
|
||||
- 接口层负责抛出或透传标准化错误，不负责直接渲染 UI
|
||||
- 不要把底层错误文本原样暴露给页面做业务判断
|
||||
- 页面只依赖可行动的信息，例如状态码、错误码、错误类型
|
||||
- 同类接口的错误处理方式要一致，避免部分返回 `null`、部分直接抛错
|
||||
|
||||
## 变更与兼容性
|
||||
|
||||
修改已有接口前先检查：
|
||||
|
||||
- 是否已有页面、Hook、组件依赖当前签名
|
||||
- 是否可以通过“新增字段/新增方法”代替破坏式修改
|
||||
- 是否需要同步调整对应类型定义与页面消费逻辑
|
||||
|
||||
推荐顺序：
|
||||
|
||||
1. 先新增兼容字段或新方法
|
||||
2. 逐步迁移调用方
|
||||
3. 最后再移除旧结构
|
||||
@@ -0,0 +1,272 @@
|
||||
# 设计变量使用规范
|
||||
|
||||
> 基于 `@oppein-react/design-tokens` 的前端样式实现规范。
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
本规范用于统一项目中颜色、间距、字体、圆角、阴影和主题语义变量的使用方式，避免出现以下问题：
|
||||
|
||||
- 同一项目内同时混用 token、硬编码 HEX 和临时样式值
|
||||
- 视觉稿已统一，但代码层无法稳定复用设计变量
|
||||
- 亮暗主题切换时，组件样式无法跟随语义变量变化
|
||||
- 业务组件直接依赖底层常量，导致样式难以替换和升级
|
||||
|
||||
核心原则：
|
||||
|
||||
1. 业务样式优先消费 CSS 变量或 UnoCSS token class
|
||||
2. 语义优先于具体色值，优先写 `var(--op-primary)` 而不是固定品牌阶值
|
||||
3. 亮暗主题切换统一通过 `.dark` 类名驱动，不在组件内自行维护双份颜色
|
||||
4. TypeScript token 常量仅用于脚本、配置、图表主题等非 CSS 场景
|
||||
|
||||
---
|
||||
|
||||
## 安装与接入
|
||||
|
||||
### 包安装
|
||||
|
||||
- 外部项目需要先配置 npm registry，再安装 `@oppein-react/design-tokens`
|
||||
- monorepo 内部 workspace 包，依赖统一写成 `"@oppein-react/design-tokens": "workspace:*"`
|
||||
- 设计变量包是叶子包，不应再反向依赖业务包
|
||||
|
||||
### CSS 注入
|
||||
|
||||
- 应用入口必须导入 `@oppein-react/design-tokens/css`
|
||||
- 入口导入只能做一次，避免在页面组件或局部样式文件重复注入
|
||||
- 推荐放在 `src/main.ts` 或应用级入口文件
|
||||
|
||||
示例：
|
||||
|
||||
```ts
|
||||
import "@oppein-react/design-tokens/css";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 样式消费规则
|
||||
|
||||
### 1. CSS 变量
|
||||
|
||||
适用场景：
|
||||
|
||||
- 组件样式文件
|
||||
- CSS Modules
|
||||
- 全局样式
|
||||
- 需要跟随暗色主题自动切换的颜色、阴影、背景、边框
|
||||
|
||||
规则：
|
||||
|
||||
- 全局 CSS 变量统一使用 `--op-` 前缀
|
||||
- 颜色优先使用语义变量，如 `--op-primary`、`--op-background`、`--op-foreground`
|
||||
- 只有在明确需要某个色板阶值时，才使用 `--op-color-brand-6` 这类全局色板变量
|
||||
- 间距、圆角、阴影统一使用 token 变量，不要自己再写一套近似值
|
||||
|
||||
示例：
|
||||
|
||||
```css
|
||||
.page {
|
||||
color: var(--op-foreground);
|
||||
background: var(--op-background);
|
||||
}
|
||||
|
||||
.primary-button {
|
||||
color: var(--op-color-white);
|
||||
background: var(--op-primary);
|
||||
border-radius: var(--op-radius-button);
|
||||
box-shadow: var(--op-shadow-1);
|
||||
padding: var(--op-spacing-xs) var(--op-spacing-sm);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. UnoCSS token class
|
||||
|
||||
适用场景：
|
||||
|
||||
- 项目已经启用 UnoCSS
|
||||
- 样式以原子类为主，且希望直接映射设计 token
|
||||
|
||||
规则：
|
||||
|
||||
- `uno.config.ts` 中统一启用 `presetOppein()`
|
||||
- 业务代码直接使用 token class，如 `bg-background`、`text-foreground`、`rounded-card`
|
||||
- 不要一边启用 preset，一边继续大面积写无语义的颜色 class 或硬编码 style
|
||||
- 如需覆盖品牌主色，可在 `presetOppein({ primary })` 中配置，不在业务组件中零散覆盖
|
||||
|
||||
示例：
|
||||
|
||||
```ts
|
||||
import { defineConfig, presetUno } from "unocss";
|
||||
import { presetOppein } from "@oppein-react/design-tokens/unocss";
|
||||
|
||||
export default defineConfig({
|
||||
presets: [presetUno(), presetOppein()],
|
||||
});
|
||||
```
|
||||
|
||||
```tsx
|
||||
export function Example() {
|
||||
return (
|
||||
<div className="bg-background text-foreground p-md rounded-card">
|
||||
<button className="bg-primary text-white px-sm py-xs rounded-button">
|
||||
保存
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 变量选择顺序
|
||||
|
||||
新增样式时，按以下顺序选择 token：
|
||||
|
||||
1. 先找语义变量
|
||||
例如：`--op-primary`、`--op-background-secondary`、`--op-border`
|
||||
2. 再找语义尺寸变量
|
||||
例如：`--op-spacing-md`、`--op-radius-card`、`--op-shadow-2`
|
||||
3. 最后才使用全局色板阶值
|
||||
例如：`--op-color-brand-6`
|
||||
|
||||
只有在以下场景允许直接使用色板阶值：
|
||||
|
||||
- 图表配色
|
||||
- 特殊插画或装饰性视觉
|
||||
- 设计稿明确指定阶值，而不是语义角色
|
||||
|
||||
---
|
||||
|
||||
## 主题切换规则
|
||||
|
||||
- 亮色主题默认挂在 `:root`
|
||||
- 暗色主题统一挂在 `.dark`
|
||||
- 切换主题时，只允许操作根节点的 `dark` 类名
|
||||
- 禁止在业务组件内通过条件分支手写两套 HEX 颜色实现明暗主题
|
||||
|
||||
示例：
|
||||
|
||||
```ts
|
||||
document.documentElement.classList.toggle("dark", isDark);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TypeScript 常量使用边界
|
||||
|
||||
`@oppein-react/design-tokens` 导出的 `colors`、`spacing`、`radius`、`shadows`、`lightTheme`、`darkTheme` 适用于：
|
||||
|
||||
- 图表主题
|
||||
- JS 配置对象
|
||||
- 运行时计算
|
||||
- 非 CSS 场景的默认值或映射表
|
||||
|
||||
禁止把这些常量当作业务组件样式的默认写法，尤其不要在 JSX 内直接硬塞原始色值：
|
||||
|
||||
```ts
|
||||
import { colors, lightTheme, radius, spacing } from "@oppein-react/design-tokens";
|
||||
|
||||
const primary = colors.brand[6];
|
||||
const pageBackground = lightTheme.background;
|
||||
const cardRadius = radius.card;
|
||||
const gap = spacing.md;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 禁止行为
|
||||
|
||||
- 在组件、页面、全局样式中硬编码颜色值，如 `#3370FF`、`rgba(0,0,0,.12)`，而对应 token 已存在
|
||||
- 新增一套项目私有的 `--primary`、`--brand-blue` 之类变量，与 `--op-` 体系并行
|
||||
- 在组件内部手动维护亮色和暗色两套颜色常量
|
||||
- CSS 变量已经能表达的场景，仍在 JS 中拼接大量内联样式对象
|
||||
- 为了局部视觉效果随意创造规范外阴影、圆角和间距值
|
||||
|
||||
---
|
||||
|
||||
## Wrong vs Correct
|
||||
|
||||
### 颜色
|
||||
|
||||
#### Wrong
|
||||
|
||||
```css
|
||||
.tab-active {
|
||||
color: #3370ff;
|
||||
border-color: #3370ff;
|
||||
}
|
||||
```
|
||||
|
||||
#### Correct
|
||||
|
||||
```css
|
||||
.tab-active {
|
||||
color: var(--op-primary);
|
||||
border-color: var(--op-primary);
|
||||
}
|
||||
```
|
||||
|
||||
### 圆角与阴影
|
||||
|
||||
#### Wrong
|
||||
|
||||
```css
|
||||
.card {
|
||||
border-radius: 15px;
|
||||
box-shadow: 0 6px 18px rgba(17, 26, 44, 0.08);
|
||||
}
|
||||
```
|
||||
|
||||
#### Correct
|
||||
|
||||
```css
|
||||
.card {
|
||||
border-radius: var(--op-radius-card);
|
||||
box-shadow: var(--op-shadow-2);
|
||||
}
|
||||
```
|
||||
|
||||
### 主题切换
|
||||
|
||||
#### Wrong
|
||||
|
||||
```tsx
|
||||
const style = {
|
||||
color: isDark ? "#ffffff" : "#1f2329",
|
||||
background: isDark ? "#141414" : "#ffffff",
|
||||
};
|
||||
```
|
||||
|
||||
#### Correct
|
||||
|
||||
```tsx
|
||||
document.documentElement.classList.toggle("dark", isDark);
|
||||
```
|
||||
|
||||
```css
|
||||
.panel {
|
||||
color: var(--op-foreground);
|
||||
background: var(--op-background);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发与验收清单
|
||||
|
||||
提交前至少确认：
|
||||
|
||||
- 入口是否已注入 `@oppein-react/design-tokens/css`
|
||||
- 颜色、圆角、阴影、间距是否优先使用了 `--op-` 变量
|
||||
- 可用语义变量时，是否避免了直接写色板阶值
|
||||
- 是否避免新增硬编码 HEX、RGB、RGBA
|
||||
- 暗色模式是否通过 `.dark` 驱动，而不是组件局部条件分支
|
||||
- 项目启用 UnoCSS 时，是否已优先使用 token class 而非重复造 class
|
||||
|
||||
---
|
||||
|
||||
## 相关规范
|
||||
|
||||
- 视觉语义与组件形态：`DESIGN.md`
|
||||
- 目录和样式归属：`frontend-structure-guidelines.md`
|
||||
- 提交前检查：`quality-guidelines.md`
|
||||
@@ -0,0 +1,73 @@
|
||||
# 类型定义规范
|
||||
|
||||
> 前端请求参数、响应数据类型以及页面数据模型的定义规范。
|
||||
|
||||
---
|
||||
|
||||
## 命名原则
|
||||
|
||||
- 类型名要体现用途，例如 `LoginParams`、`OrderListItem`、`UserDetailResponse`
|
||||
- 优先使用业务语义命名，不用后端传输层术语硬套前端场景
|
||||
- 名称要与实际使用场景一致，不要出现“通用类型”却只服务单一页面的情况
|
||||
- 页面私有类型优先就近定义在页面目录；全局复用类型再抽到公共位置
|
||||
|
||||
---
|
||||
|
||||
## 字段设计原则
|
||||
|
||||
- 只保留当前页面、组件、Hook 真实需要的字段
|
||||
- 字段语义必须单一明确，不要一个字段承担多种含义
|
||||
- 嵌套对象只在确实提升可读性时使用，避免过深层级
|
||||
- 能用稳定基础类型表达的，不要额外包一层无意义对象
|
||||
- 禁止为了“以后可能会用”提前塞入无消费方字段
|
||||
|
||||
---
|
||||
|
||||
## 类型边界
|
||||
|
||||
- 区分“接口原始返回类型”和“页面消费后的展示类型”
|
||||
- 不要把后端所有字段原样铺到页面组件 props 中
|
||||
- 页面展示需要格式化、组合、兜底时，应在 `utils/` 或 `hooks/` 做转换
|
||||
- 同一个后端实体被多个页面以不同方式使用时，允许定义多个前端视图类型
|
||||
|
||||
---
|
||||
|
||||
## 默认值与可选值
|
||||
|
||||
- 可选字段要明确标注 `?`，不要靠调用方猜测
|
||||
- 默认值策略必须显式，不要把隐式兜底散落在多个组件里
|
||||
- 会影响页面分支逻辑的字段，必须明确说明为空时的处理方式
|
||||
- 列表字段默认值、布尔字段默认值、文本占位值等应在消费层统一处理
|
||||
|
||||
---
|
||||
|
||||
## 映射规范
|
||||
|
||||
- 映射的目标是让页面更好用，不是机械复制后端结构
|
||||
- 不要保留“临时透传字段”或无人消费的中间字段
|
||||
- 若多个页面需要不同数据形状，应该拆成不同类型，而不是堆成一个超大类型
|
||||
- 时间、金额、状态文案等展示型字段，优先通过派生字段生成，避免在组件内部重复处理
|
||||
|
||||
## 前端类型安全
|
||||
|
||||
- 禁止在新增代码中使用无约束的 `any`
|
||||
- 对枚举值、状态值、字典值，优先用联合类型或 `enum` 明确约束
|
||||
- 组件 Props 类型要最小化，只暴露组件真正需要的数据
|
||||
- 需要缓存、比较、序列化的数据结构，应保持简单、稳定、可预期
|
||||
|
||||
## 示例
|
||||
|
||||
```ts
|
||||
export type KnowledgeListParams = {
|
||||
keyword?: string;
|
||||
pageNo: number;
|
||||
pageSize: number;
|
||||
};
|
||||
|
||||
export type KnowledgeListItem = {
|
||||
id: string;
|
||||
title: string;
|
||||
status: "draft" | "published";
|
||||
updatedAt: string;
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,221 @@
|
||||
# 前端目录与代码放置规范
|
||||
|
||||
> 说明真实分层、目录职责和新增代码放置规则。
|
||||
|
||||
---
|
||||
|
||||
## 适用范围
|
||||
|
||||
单包 Vite + React/Vue + TypeScript 项目。
|
||||
|
||||
---
|
||||
|
||||
## src 根目录结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # 业务接口入口，按领域拆文件并统一导出
|
||||
├── assets/ # 静态资源占位目录
|
||||
├── common/ # 站点级常量、配置、静态数据、共享类型
|
||||
├── components/ # 跨页面复用组件
|
||||
├── hooks/ # 跨页面复用的 Hooks (React) / Composables (Vue)
|
||||
├── pages/ # 路由页面
|
||||
├── router/ # 路由配置
|
||||
├── styles/ # 全局样式入口
|
||||
├── utils/ # 通用工具
|
||||
├── App.tsx # 应用壳 (React 为 .tsx，Vue 为 .vue)
|
||||
└── main.ts # 启动入口
|
||||
```
|
||||
|
||||
新增目录前先判断能否归入已有层级；不要为了单个文件再造一层。
|
||||
|
||||
---
|
||||
|
||||
## 各层职责
|
||||
|
||||
### `src/api`
|
||||
|
||||
用于集中管理接口方法，按业务域拆分，例如：
|
||||
|
||||
- `api-user.ts`
|
||||
- `api-order.ts`
|
||||
- `api-product.ts`
|
||||
|
||||
约束：
|
||||
|
||||
- 文件名统一使用 `api-*.ts`
|
||||
- 所有接口通过 `src/api/index.ts` 暴露
|
||||
- 页面、组件、Hook 不直接拼 URL 或内联请求逻辑
|
||||
|
||||
### `src/common`
|
||||
|
||||
放站点级共享数据和基础类型，不放页面局部常量。
|
||||
|
||||
典型内容：
|
||||
|
||||
- `config.ts`
|
||||
- `constants.ts`
|
||||
- `enum.ts`
|
||||
- `site-data.ts`
|
||||
- `site-types.ts`
|
||||
|
||||
站点级常量、配置、枚举、共享类型优先放此处；可远程获取的数据优先通过 `api/` + 页面 Hooks 获取，不要堆积在 `common/`。
|
||||
|
||||
### `src/components`
|
||||
|
||||
放多个页面都会复用的通用组件和布局组件。
|
||||
|
||||
典型示例：
|
||||
|
||||
- `layout-shell.tsx` (React) / `layout-shell.vue` (Vue)
|
||||
- `nav-header.tsx` / `nav-header.vue`
|
||||
- `content-card.tsx` / `content-card.vue`
|
||||
- `loading-state.tsx` / `loading-state.vue`
|
||||
- `empty-state.tsx` / `empty-state.vue`
|
||||
- `modal-common.tsx` / `modal-common.vue`
|
||||
|
||||
约束：
|
||||
|
||||
- 文件名统一使用小写横杠
|
||||
- 只有跨页面复用的组件才放这里
|
||||
- 某个页面特有的展示块，优先直接放该页面目录下，避免过早公共化
|
||||
|
||||
### `src/hooks`
|
||||
|
||||
放跨页面复用的状态与异步逻辑。React 中称为 Hooks，Vue 中称为 Composables。
|
||||
|
||||
典型示例：
|
||||
|
||||
- `use-promise-data.ts`
|
||||
- `use-form.ts`
|
||||
- `use-modal.ts`
|
||||
- `use-table.ts`
|
||||
|
||||
约束：
|
||||
|
||||
- 文件名统一使用 `use-*.ts`（React Hooks 和 Vue Composables 均遵循此命名）
|
||||
- 负责复用逻辑，不负责路由结构和大块 UI 拼装
|
||||
|
||||
### `src/pages`
|
||||
|
||||
页面层按路由语义组织，一个目录对应一个页面或页面组。
|
||||
|
||||
典型结构：
|
||||
|
||||
```
|
||||
pages/
|
||||
├── home/index.tsx (或 index.vue)
|
||||
├── list/index.tsx (或 index.vue)
|
||||
├── list/detail/index.tsx (或 index.vue)
|
||||
├── admin/index.tsx (或 index.vue)
|
||||
└── admin/components/admin-table.tsx (或 .vue)
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 路由页面入口统一使用 `index.tsx` (React) 或 `index.vue` (Vue)
|
||||
- 有明确子路由的页面，使用目录嵌套表达层级，例如 `list/detail/`
|
||||
- 页面目录名统一使用小写横杠，例如 `order-detail/` 而非 `orderDetail/`
|
||||
- 仅后台页面共享的组件，放在 `pages/admin/components/`，不要提到全局 `components/`
|
||||
- 如果未来某个页面出现多个私有组件、Hook、转换函数，可以在该页面目录下新增 `components/`、`hooks/`、`utils/` 子目录；尚未形成稳定模式前，不要预先创建空目录
|
||||
|
||||
### `src/router`
|
||||
|
||||
集中声明路由和布局装配关系，例如通过 layout route 划分不同壳层。
|
||||
|
||||
|
||||
### `src/utils`
|
||||
|
||||
放纯工具函数和请求封装，不承载业务页面状态。
|
||||
|
||||
典型文件：
|
||||
|
||||
- `request.ts`
|
||||
- `format.ts`
|
||||
- `storage.ts`
|
||||
- `validate.ts`
|
||||
|
||||
请求封装、通用工具函数优先放在此处，不要散落到页面或 `api-*` 文件中。
|
||||
|
||||
### `src/styles`
|
||||
|
||||
全局样式入口和主题变量注入位置。
|
||||
|
||||
职责：
|
||||
|
||||
- 导入设计变量包 CSS，如 `@your-design-system/tokens/css`
|
||||
- 全局基础样式、重置样式、通用动画
|
||||
- 禁止在组件内重复引入设计变量 CSS，统一从 `styles/` 入口注入
|
||||
|
||||
### `src/assets`
|
||||
|
||||
静态资源占位目录。
|
||||
|
||||
职责：
|
||||
|
||||
- 存放图片、字体、SVG 等静态文件
|
||||
- 通过 Vite 自动处理路径引用，禁止手写相对路径拼接到 `public/`
|
||||
- 单个页面私有的静态资源，优先放在该页面目录下
|
||||
|
||||
---
|
||||
|
||||
## 命名约定速查
|
||||
|
||||
| 类型 | 命名规则 | 示例 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 接口文件 | `api-{domain}.ts` | `api-user.ts` | 按业务域拆分，统一从 `index.ts` 导出 |
|
||||
| Hook/Composable 文件 | `use-{feature}.ts` | `use-form.ts` | React Hooks / Vue Composables 通用命名 |
|
||||
| 组件文件 | 小写横杠 | `content-card.tsx` / `.vue` | 仅跨页面复用的组件 |
|
||||
| 页面入口 | `index.tsx` / `index.vue` | `pages/home/index.tsx` | 每个路由页面对应一个入口 |
|
||||
| 页面目录 | 小写横杠 | `order-detail/` | 有子路由时使用目录嵌套 |
|
||||
| 工具文件 | 小写横杠 | `format.ts` | 纯函数，不承载业务状态 |
|
||||
| 样式文件 | 小写横杠 | `index.css` | 全局样式入口 |
|
||||
|
||||
---
|
||||
|
||||
## 新增代码放置规则
|
||||
|
||||
### 新增页面
|
||||
|
||||
- 新页面先放到 `src/pages/<route-segment>/index.tsx` (React) 或 `index.vue` (Vue)
|
||||
- 有详情页或子页时，用子目录表达路由层级
|
||||
- 页面只负责组装，不要把可复用块全部堆进页面入口文件
|
||||
|
||||
### 新增共享组件
|
||||
|
||||
满足下面任一条件才放 `src/components/`：
|
||||
|
||||
- 至少被两个页面复用
|
||||
- 明显属于布局壳、空态、加载态、卡片、分页这类跨页面基础组件
|
||||
|
||||
否则放到对应页面目录下。
|
||||
|
||||
### 新增接口
|
||||
|
||||
- 按业务域加到现有 `api-*.ts`，不要为单个接口新建零散文件
|
||||
- 新增业务域时，才创建新的 `api-<domain>.ts`
|
||||
- 同步更新 `src/api/index.ts`
|
||||
|
||||
### 新增共享数据或类型
|
||||
|
||||
- 纯配置、导航、枚举、常量放 `src/common/`
|
||||
- 类型优先就近放到使用域；只有被多个页面共享时，才进入 `site-types.ts` 或拆新的共享类型文件
|
||||
|
||||
---
|
||||
|
||||
## 反模式
|
||||
|
||||
- 把接口请求直接写进页面组件，绕过 `src/api/`
|
||||
- 把后台专用页面组件放进全局 `src/components/`
|
||||
- 为了“看起来规范”预先创建大量空的页面私有 `hooks/`、`utils/`、`components/`
|
||||
- 把路由层级和目录层级写反，例如把详情页和列表页并列平铺但路由嵌套
|
||||
- 在 `common/` 堆放只给单页使用的常量或转换函数
|
||||
|
||||
---
|
||||
|
||||
## 修改前检查
|
||||
|
||||
- 这段代码是路由页面、共享组件、共享 Hook/Composable、共享数据，还是接口定义？
|
||||
- 这个文件未来是否很可能被第二个页面复用？
|
||||
- 是否应该先并入现有业务域文件，而不是新造目录？
|
||||
- 是否和 `src/router/` 的路由分组保持一致？
|
||||
@@ -0,0 +1,95 @@
|
||||
# 前端开发规范
|
||||
|
||||
> 前端开发的总入口，覆盖目录组织、接口设计、类型定义、UI 实现与质量要求。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本规范用于统一前端项目的开发方式，目标是让代码在以下几个方面保持稳定：
|
||||
|
||||
- 可读：目录、命名、职责边界清晰，方便快速定位代码
|
||||
- 可维护：页面逻辑拆分合理，避免巨型组件和重复实现
|
||||
- 可复用：公共能力与页面私有能力边界明确，减少污染
|
||||
- 可演进：接口、类型、页面结构支持逐步扩展，不因小改动造成大面积返工
|
||||
|
||||
核心原则：
|
||||
|
||||
1. 就近原则：只在当前页面使用的代码，放在当前页面目录下
|
||||
2. 分层清晰：全局公共层、页面私有层、接口层各司其职
|
||||
3. 命名统一：文件名、目录名、Hooks、弹窗组件遵循固定规则
|
||||
4. 类型明确：接口参数、返回值、组件 Props、状态值都应具备清晰类型
|
||||
5. 优先复用：抽公共前先确认真的复用，抽公共后保持通用而不过度设计
|
||||
|
||||
---
|
||||
|
||||
## 编码环境
|
||||
|
||||
- Vue / React，使用 TypeScript
|
||||
- Vite、路由库（React Router / Vue Router）、Axios 等常见前端库
|
||||
|
||||
---
|
||||
|
||||
## 开发前检查清单
|
||||
|
||||
开始修改前端代码前，请先确认：
|
||||
|
||||
1. 这次改动是否真的属于前端层，而不是后端或其它层
|
||||
2. 需求影响的是全局公共能力，还是某个页面私有能力
|
||||
3. 涉及接口时，参数、返回值、错误处理方式是否已经明确
|
||||
4. 涉及样式、主题或视觉变量时，是否优先使用 `@oppein-react/design-tokens`
|
||||
5. 新增命名是否使用业务语义，而不是后端表结构或临时术语
|
||||
6. 是否有现成组件、Hooks、工具函数、类型定义或设计 token 可以复用
|
||||
7. 改动是否会影响现有页面、公共组件或既有接口调用方式
|
||||
|
||||
---
|
||||
|
||||
## 规范索引
|
||||
|
||||
| 规范 | 作用 | 适用场景 |
|
||||
|---|---|---|
|
||||
| [前端结构规范](./frontend-structure-guidelines.md) | 约束 `src` 下各层目录职责、页面私有结构和命名方式 | 新建页面、重构目录、抽离公共能力前必读 |
|
||||
| [UI 设计规范](../../../DESIGN.md) | 规范界面实现方式、视觉一致性和交互呈现 | 新做页面、优化样式、补充组件展示时阅读 |
|
||||
| [设计变量使用规范](./design-tokens-guidelines.md) | 规范 `@oppein-react/design-tokens` 的接入、变量消费、主题切换与 UnoCSS 使用方式 | 新增样式、主题切换、替换硬编码颜色、接入 UnoCSS token 时必读 |
|
||||
| [接口契约规范](./api-guidelines.md) | 规范前端接口文件、请求封装、错误处理和兼容性 | 新增接口、调整请求参数、封装请求工具时阅读 |
|
||||
| [类型定义规范](./dto-guidelines.md) | 规范请求参数、响应数据、页面消费模型和类型边界 | 新增类型、重构数据结构、拆分页面模型时阅读 |
|
||||
| [质量规范](./quality-guidelines.md) | 规范代码质量、拆分方式、验证要求和评审重点 | 开发中自检、提测前、收尾时阅读 |
|
||||
|
||||
---
|
||||
|
||||
## 推荐使用方式
|
||||
|
||||
可以把这套规范理解成一个简单流程：
|
||||
|
||||
1. 先看 `frontend-structure-guidelines.md`
|
||||
确认代码该放全局、页面私有，还是接口层
|
||||
2. 涉及样式、主题和设计变量时看 `design-tokens-guidelines.md` 和 `DESIGN.md`
|
||||
确保颜色、间距、圆角、阴影、亮暗主题实现方式一致
|
||||
3. 涉及请求与数据时看 `api-guidelines.md` 和 `dto-guidelines.md`
|
||||
确保接口定义、类型建模、页面消费方式一致
|
||||
4. 涉及页面与交互时看 `DESIGN.md`
|
||||
保证页面结构、交互体验与视觉实现符合要求
|
||||
5. 提交前看 `quality-guidelines.md`
|
||||
做最后的质量自检与风险排查
|
||||
|
||||
---
|
||||
|
||||
## 完成前自检
|
||||
|
||||
完成前端改动前，至少确认以下几点：
|
||||
|
||||
- 目录层级是否正确，页面私有代码是否已就近放置
|
||||
- 接口是否统一从约定目录导出，是否避免了页面内联请求实现
|
||||
- 类型是否明确，是否避免了新增 `any`
|
||||
- 样式是否优先使用了 `@oppein-react/design-tokens` 的语义变量或 UnoCSS token class
|
||||
- 页面是否拆分合理，是否把复杂逻辑从主页面组件下沉
|
||||
- 公共能力是否真的具备复用价值，而不是过早抽象
|
||||
- 构建是否通过，关键路径是否完成本地验证
|
||||
|
||||
---
|
||||
|
||||
## 语言要求
|
||||
|
||||
- 所有规范文档、注释、提交信息统一使用**简体中文**
|
||||
- 代码中的变量名、函数名、类型名可以使用英文
|
||||
- 命名应优先体现业务语义，避免使用模糊缩写与临时命名
|
||||
@@ -0,0 +1,55 @@
|
||||
# 前端质量规范
|
||||
|
||||
> 前端代码质量、可维护性与交付前检查规范。
|
||||
|
||||
---
|
||||
|
||||
## 必须遵守
|
||||
|
||||
- 页面主文件聚焦页面组装,复杂逻辑下沉到 `components/`、`hooks/`、`utils/`
|
||||
- 目录与命名遵循 `frontend-structure-guidelines.md` 约定
|
||||
- 接口层、页面层、公共层职责明确,不交叉污染
|
||||
- 新增类型、常量、工具函数前先搜索是否已有可复用实现
|
||||
- 公共组件保持通用,页面私有组件就近放置
|
||||
|
||||
---
|
||||
|
||||
## 禁止行为
|
||||
|
||||
- 页面直接内联大段请求逻辑,绕过 `api/` 或页面私有接口文件
|
||||
- 本应页面私有的组件、Hooks、工具函数被随意放进全局公共目录
|
||||
- 组件 Props、接口返回值、Hook 返回值大量使用 `any`
|
||||
- 在组件渲染过程中执行复杂计算、重复格式化、重复创建临时对象而不做整理
|
||||
- 一个页面目录里同时堆放列表、详情、弹窗、表单等多种耦合逻辑却不拆分
|
||||
- 把样式、请求、副作用、状态管理全部写进一个超大组件
|
||||
|
||||
---
|
||||
|
||||
## GIT提交规范
|
||||
|
||||
- 所有AI生成的代码提交必须在Git commit message中标识AI模型名称,格式为 `[AI-{模型名称}]`,例如 `[AI-Qoder] 添加用户列表页面`
|
||||
|
||||
---
|
||||
|
||||
## 测试要求
|
||||
|
||||
至少需要验证:
|
||||
|
||||
- 页面能正常渲染,关键交互路径不报错
|
||||
- 新增或修改的接口调用参数、返回值与页面消费逻辑一致
|
||||
- 条件渲染、空态、加载态、异常态至少人工验证一遍
|
||||
- 抽取出的工具函数、格式化函数、状态转换函数应补单元测试(如果项目已具备测试设施)
|
||||
- 改动公共组件或公共 Hook 时,要确认现有调用方未被破坏
|
||||
|
||||
如果项目暂时没有完整测试设施,至少保证能通过构建,并完成核心路径的本地人工验证。
|
||||
|
||||
---
|
||||
|
||||
## 代码审查清单
|
||||
|
||||
- 这个改动是否放在了正确目录,而不是图省事塞进页面主文件?
|
||||
- 新增公共能力之前,是否确认过它不是页面私有逻辑?
|
||||
- 是否存在命名模糊、职责混乱、目录层级不清的问题?
|
||||
- 接口、类型、组件、Hooks 之间的数据流是否清晰可读?
|
||||
- 是否引入了重复实现,本可以复用已有工具或组件?
|
||||
- 构建、类型检查、本地页面验证是否已经完成?
|
||||
Reference in New Issue
Block a user