lc-workflow

lc-workflow 是一个项目级 AI 开发工作流框架。它的目标不是只生成一份轻量简介，而是在任意项目中执行 lc init 后，建立一套可持续协助开发的上下文、规范、任务状态机和验证门禁。

它会为项目生成：

• .lc/project.md：项目上下文摘要，记录入口、模块分布、热点文件、风险和工作流建议，并保留可人工维护的项目说明区；
• .lc/context/*.json：机器可读的项目地图、文件清单、命令索引、预计算调用链、聚类、热点和置信度上下文包；
• .lc/spec/：团队长期规范、架构边界、质量门禁和 AI 工作流规则；
• .lc/tasks/{task}/：每个需求的 PRD、计划、研究上下文、检查清单和评审记录；
• .lc/reports/：每次验证门禁生成的检查报告；
• .claude/commands/lc/、.claude/skills/、.cursor/rules/：让 Claude Code / Cursor 按项目流程工作。

安装

npm install -g lc-workflow

也可以直接使用最新版：

npx lc-workflow@latest init

快速开始

进入任意项目根目录：

lc init "项目摘要，可选"

lc init 会生成模板，并默认立即运行项目分析与结构化索引，输出 .lc/project.md、.lc/context/project-map.json、.lc/context/agent-context.json、.lc/context/retrieval-index.json 和 .lc/context/semantic-index.json；.lc/spec/project/overview.md 的人工说明区会被保留，后续分析只刷新自动快照。

如果是在另一个项目里通过 npm install 升级/测试新版本，重新运行一次 lc init "项目摘要" 会刷新 .lc/scripts/、Claude 命令、Cursor 规则等机器生成运行时，并重新生成轻量检索索引；不需要 --force 覆盖人工维护的 spec/项目说明。

如果只想生成模板，不立即分析：

lc init --no-analyze

查看当前工作流状态：

lc status

只想判断改动边界、调用关系或影响范围，不创建任务：

lc context "toggleTheme 调用关系"

小型单点修改可以走轻量流：先查 boundary，再做最小改动，不生成完整 PRD/plan/review：

lc quick "修复 toggleTheme 状态同步"

创建一个可追踪任务：

lc task "实现用户登录"
lc task "实现用户登录" --slug login --priority P1 --assignee alice

在 Claude Code 中可以使用：

/lc:context toggleTheme 调用关系
/lc:quick 修复 toggleTheme 状态同步
/lc:start 实现用户登录
/lc:status
/lc:check
/lc:finish

项目级流程

1. 项目上下文

初始化或项目结构变化后运行：

node ./.lc/scripts/analyze-project.js "项目摘要"
node ./.lc/scripts/context-index.js

输出：

• .lc/project.md
• .lc/spec/project/overview.md 的自动分析快照
• .lc/context/project-map.json
• .lc/context/files.json
• .lc/context/commands.json
• .lc/context/agent-context.json：给 AI/MCP 的 token 友好上下文摘要，包含入口、调用链、聚类、热点、置信度、检索策略和 token 预算摘要
• .lc/context/retrieval-index.json：MCP/CLI 默认使用的轻量检索索引，用于按 query 返回 matchedFiles、改动边界和依赖/被依赖关系
• .lc/context/semantic-index.json：完整预计算语义索引，供 query 检索和深度分析使用，不建议默认整文件读取

AI 开始任务前优先用 query 检索和边界判断，而不是盲目扫描全部源码或直接修改第一个命中的文件。agent-context.json 会保留压缩后的关键图谱，并写入 contextBudget 显示 compact/retrieval/full 字节数、估算 token 和压缩比例；默认 MCP/CLI 读取 retrieval-index.json，返回 matchedFiles 与 boundary（editCandidates、importedBy/calledBy、direct imports、sameCluster）。只有公共契约、跨层状态或边界证据不足时，才显式请求 depth: "graph"、includeGraph: true 或 allowLarge: true 加载完整 semantic-index.json。任务改变项目定位、核心目标、模块边界或领域术语时，收尾阶段应同步更新 .lc/project.md 和 .lc/spec/project/。

如果编辑器支持 MCP，可使用生成的 .mcp.json 启动：

node ./.lc/scripts/mcp-server.js
# 或安装 CLI 后：
lc mcp

MCP 工具 lc_context 默认按 query 返回“候选改动点 + 关联边界 + 读取计划”，而不是直接返回完整索引：

{
  "query": "要实现或排查的功能、文件名、符号名",
  "maxTokens": 1800,
  "topK": 5,
  "depth": "files"
}

默认返回内容包含 matchedFiles、boundary、相关 clusters 和后续 get-context --mode file --max-files 3 --max-chars 12000 / rg 命令建议。agent 必须先说明为什么 editCandidates 是改动点、会影响哪些 importedBy/calledBy/direct imports、如何验证，再开始修改。需要更多符号时传 depth: "symbols"；需要调用/导入完整边时才传 depth: "graph" 或 includeGraph: true。detail: "full" 默认只返回保护提示；只有手动诊断且显式传 allowLarge: true 时才会返回完整 .lc/context/semantic-index.json。默认 MCP 输出为压缩 JSON；需要人工阅读时传 pretty: true。

2. 任务状态机

每个开发任务都有明确状态：

| 状态 | 含义 | |---|---| | planning | 需求澄清、上下文收集、方案和计划 | | ready | 计划已被用户确认，等待开始实现 | | in_progress | 正在编码实现 | | verifying | 正在运行检查、修复阻塞项、写评审 | | completed | 已完成，可归档 |

常用脚本：

node ./.lc/scripts/task.js current
node ./.lc/scripts/task.js list --status planning
node ./.lc/scripts/task.js add-context <task> implement ".lc/spec/project/index.md" "实现前需要的项目规范"
node ./.lc/scripts/task.js list-context <task>
node ./.lc/scripts/task.js validate <task>
node ./.lc/scripts/task.js approve-plan
node ./.lc/scripts/task.js start <task>
node ./.lc/scripts/task.js checkpoint "完成登录接口对接"
node ./.lc/scripts/task.js verify
node ./.lc/scripts/task.js finish
node ./.lc/scripts/task.js archive <task>

3. 计划先行

实现前必须在任务目录中补齐：

• prd.md：目标、场景、需求、验收标准、范围外内容；
• research/context.md：相关入口、文件、数据流、风险和待确认问题；
• plan.md：至少两个方案、选定方案、原子步骤、涉及文件和验证方式；
• implement.jsonl / check.jsonl：精准列出实现和检查阶段需要读取的规范与研究文件。

implement.jsonl / check.jsonl 建议通过 task.js add-context 维护，并在开始实现前运行：

node ./.lc/scripts/task.js validate <task>

这两个 JSONL 只放 spec / research 文件，不预登记即将修改的业务代码。

用户确认计划后，运行：

node ./.lc/scripts/task.js approve-plan
node ./.lc/scripts/task.js start

4. 验证门禁

完成前运行：

lc check --run

或：

node ./.lc/scripts/check.js

脚本会按 .lc/config.json 中识别到的 lint、typecheck、test、build 命令执行，并写入：

.lc/reports/check-*.md

检查报告摘要需要写入当前任务 review.md。

CLI 命令

lc init [summary...]

初始化项目级工作流，并生成：

• .lc/config.json
• .lc/project.md
• .lc/context/*.json
• .lc/spec/**/*.md
• .lc/workflows/*.md
• .lc/scripts/*.js
• .lc/reports/.gitkeep
• .claude/commands/lc/*.md
• .claude/skills/*/SKILL.md
• .claude/settings.json
• .cursor/rules/lc.mdc

覆盖已有模板文件：

lc init --force

只生成模板、不分析项目：

lc init --no-analyze

lc analyze [summary...]

重新生成项目地图、自动分析快照、调用链、聚类和 MCP 上下文包：

lc analyze "项目摘要"

lc mcp

启动 stdio MCP Server，暴露 lc_context 工具：

lc mcp

lc context [query...]

只做边界查询，不创建任务、不写 PRD/plan、不修改代码：

lc context "toggleTheme 调用关系"
lc context "登录状态影响范围" --topK 8 --depth graph

输出复用 get-context --mode agent 的结构化结果，重点看：

• matchedFiles
• boundary.editCandidates
• boundary.mustInspectBeforeEdit
• readPlan.boundaryCommand
• guardrails / expandWhen

lc quick [title...]

轻量任务流，适合小型、单点、低风险修改：

lc quick "修复 toggleTheme 状态同步"

它会先运行 boundary 查询并输出 quick 规则：先解释为什么改 editCandidates、会影响哪些 importedBy/calledBy/direct imports、如何验证；只有说清楚后才改代码。边界 weak、公共契约、跨层状态或需求不清时，升级为 lc start 完整流程。

context / quick / start 的选择

| 命令 | 用途 | 是否创建任务 | 是否适合改代码 | |---|---|---:|---| | lc context | 只查候选改动点、调用关系、影响范围 | 否 | 否 | | lc quick | 小型单点修改，boundary 驱动 | 否 | 是，限最小范围 | | lc start | 中大型、高风险、需求不清或跨层改动 | 是 | 是，需完整门禁 |

lc task <title>

创建项目级任务目录：

lc task "添加价格对比页面"

指定工作流：

lc task "修复登录失败" --workflow bugfix

可选元数据：

lc task "修复登录失败" --workflow bugfix --slug fix-login --priority P1 --assignee alice --parent 2026-06-12_120000-auth

lc status

查看当前工作流状态、活跃任务、项目上下文更新时间和最近检查报告。

lc status
lc status --json

lc doctor

识别当前项目类型、语言、框架、包管理器和常见命令。

lc check

只输出建议检查命令：

lc check

执行验证门禁并生成报告：

lc check --run

推荐提交策略

建议提交：

.lc/config.json
.lc/project.md
.lc/spec/
.lc/workflows/
.lc/tasks/
.lc/context/project-map.json
.lc/context/commands.json
.claude/commands/lc/
.claude/skills/
.claude/settings.json
.cursor/rules/

按团队偏好决定是否提交完整文件清单和报告：

.lc/context/files.json
.lc/reports/

建议忽略：

.lc/workspace/
.lc/.runtime/

本地开发

npm install
npm run typecheck
npm run build
node dist/index.js init --force "lc-workflow 自身"
node dist/index.js status
node dist/index.js check --run

发布前检查：

npm run prepublishOnly

发布到 npm Registry：

npm login
npm publish

设计目标

lc-workflow 的目标不是替代 AI 编程工具，而是为它们提供项目级上下文、任务状态、团队规范和可复用验证流程，让 AI 能围绕真实项目持续协助开发。