senior-fullstack

Senior Fullstack

具备项目脚手架与代码质量分析工具的全栈开发技能。

---

目录

• 触发短语
• 工具
• 工作流
• 参考指南

---

触发短语

当你听到以下说法时使用此技能：

• "scaffold a new project"
• "create a Next.js app"
• "set up FastAPI with React"
• "analyze code quality"
• "check for security issues in codebase"
• "what stack should I use"
• "set up a fullstack project"
• "generate project boilerplate"

---

工具

决策引擎

确定性的方案选择器。给定四个假设（团队规模、发布节奏、面向用户、预算）以及可选的流量/敏感度输入，它会对四个内置方案进行排序，并返回匹配的方案、SLO 下限和指定的审批链。若缺少四个必需输入，则拒绝推荐方案。

用法：

# See all options
python scripts/fullstack_decision_engine.py --help

# Run against a sample input
python scripts/fullstack_decision_engine.py --sample

# Pick a profile from real inputs
python scripts/fullstack_decision_engine.py \
    --team-size-12mo 8 --cadence daily --user-facing true --budget 5000 \
    --traffic-p99-rps 50 --data-sensitivity pii-only

# JSON output for downstream tools
python scripts/fullstack_decision_engine.py --sample --output json

返回：匹配的方案名称、得分、满足/违反的约束、技术栈推荐、反向推荐、SLO 下限、指定审批人链以及规范参考。

该引擎编码了对话式问询所遵循的同一矩阵——当输入已知时可直接使用，或通过 cs-fullstack-engineer Agent 进行逐题问询。

---

项目脚手架生成器

生成包含样板代码的全栈项目结构。

支持的模板：

• nextjs - 采用 App Router、TypeScript、Tailwind CSS 的 Next.js 14+
• fastapi-react - FastAPI 后端 + React 前端 + PostgreSQL
• mern - 基于 TypeScript 的 MongoDB、Express、React、Node.js
• django-react - Django REST Framework + React 前端

用法：

# List available templates
python scripts/project_scaffolder.py --list-templates

# Create Next.js project
python scripts/project_scaffolder.py nextjs my-app

# Create FastAPI + React project
python scripts/project_scaffolder.py fastapi-react my-api

# Create MERN stack project
python scripts/project_scaffolder.py mern my-project

# Create Django + React project
python scripts/project_scaffolder.py django-react my-app

# Specify output directory
python scripts/project_scaffolder.py nextjs my-app --output ./projects

# JSON output
python scripts/project_scaffolder.py nextjs my-app --json

参数：

参数	说明
template	模板名称（nextjs、fastapi-react、mern、django-react）
project_name	新项目目录的名称
--output, -o	输出目录（默认：当前目录）
--list-templates, -l	列出所有可用模板
--json	以 JSON 格式输出

输出包括：

• 包含所有必要文件的项目结构
• 包配置（package.json、requirements.txt）
• TypeScript 配置
• Docker 与 docker-compose 设置
• 环境变量文件模板
• 运行项目的后续步骤

---

代码质量分析器

分析全栈代码库中的质量问题。

分析类别：

• 安全漏洞（硬编码密钥、注入风险）
• 代码复杂度指标（圈复杂度、嵌套深度）
• 依赖健康度（过时的包、已知 CVE）
• 测试覆盖率估算
• 文档质量

用法：

# Analyze current directory
python scripts/code_quality_analyzer.py .

# Analyze specific project
python scripts/code_quality_analyzer.py /path/to/project

# Verbose output with detailed findings
python scripts/code_quality_analyzer.py . --verbose

# JSON output
python scripts/code_quality_analyzer.py . --json

# Save report to file
python scripts/code_quality_analyzer.py . --output report.json

参数：

参数	说明
project_path	项目目录路径（默认：当前目录）
--verbose, -v	显示详细发现结果
--json	以 JSON 格式输出
--output, -o	将报告写入文件

输出包括：

• 综合得分（0-100）及字母等级
• 按严重程度划分的安全问题（critical、high、medium、low）
• 高复杂度文件
• 含 CVE 引用的易受攻击依赖
• 测试覆盖率估算
• 文档完整度
• 按优先级排序的建议

示例输出：

============================================================
CODE QUALITY ANALYSIS REPORT
============================================================

Overall Score: 75/100 (Grade: C)
Files Analyzed: 45
Total Lines: 12,500

--- SECURITY ---
  Critical: 1
  High: 2
  Medium: 5

--- COMPLEXITY ---
  Average Complexity: 8.5
  High Complexity Files: 3

--- RECOMMENDATIONS ---
1. [P0] SECURITY
   Issue: Potential hardcoded secret detected
   Action: Remove or secure sensitive data at line 42

---

工作流

工作流 1：启动新项目

1. 根据需求选择合适的技术栈（参见技术栈决策矩阵）
2. 生成项目脚手架
3. 验证脚手架：确认 package.json（或 requirements.txt）存在
4. 运行初始质量检查——在继续之前处理所有 P0 问题
5. 搭建开发环境

# 1. Scaffold project
python scripts/project_scaffolder.py nextjs my-saas-app

# 2. Verify scaffold succeeded
ls my-saas-app/package.json

# 3. Navigate and install
cd my-saas-app
npm install

# 4. Configure environment
cp .env.example .env.local

# 5. Run quality check
python scripts/code_quality_analyzer.py .

# 6. Start development
npm run dev

工作流 2：审计现有代码库

1. 运行代码质量分析
2. 审查安全发现——立即修复所有 P0（critical）问题
3. 重新运行分析器，确认 P0 问题已解决
4. 为 P1/P2 问题创建工单

# 1. Full analysis
python scripts/code_quality_analyzer.py /path/to/project --verbose

# 2. Generate detailed report
python scripts/code_quality_analyzer.py /path/to/project --json --output audit.json

# 3. After fixing P0 issues, re-run to verify
python scripts/code_quality_analyzer.py /path/to/project --verbose

工作流 3：技术栈选择

使用技术栈指南评估选项：

1. 是否需要 SEO？ → 使用带 SSR 的 Next.js
2. 后端是否以 API 为主？ → 单独使用 FastAPI 或 NestJS
3. 是否需要实时功能？ → 添加 WebSocket 层
4. 团队专长 → 根据团队技能匹配技术栈

详细比较请参阅 references/tech_stack_guide.md。

---

参考指南

架构模式（references/architecture_patterns.md）

• 前端组件架构（原子设计、容器/展示组件）
• 后端模式（整洁架构、仓储模式）
• API 设计（REST 约定、GraphQL 模式设计）
• 数据库模式（连接池、事务、只读副本）
• 缓存策略（旁路缓存、HTTP 缓存标头）
• 身份验证架构（JWT + 刷新令牌、会话）

开发工作流（references/development_workflows.md）

• 本地开发环境设置（Docker Compose、环境配置）
• Git 工作流（主干开发、约定式提交）
• CI/CD 流水线（GitHub Actions 示例）
• 测试策略（单元测试、集成测试、端到端测试）
• 代码审查流程（PR 模板、检查清单）
• 部署策略（蓝绿部署、金丝雀发布、功能标志）
• 监控与可观测性（日志、指标、运行状况检查）

技术栈指南（references/tech_stack_guide.md）

• 前端框架比较（Next.js、React+Vite、Vue）
• 后端框架（Express、Fastify、NestJS、FastAPI、Django）
• 数据库选择（PostgreSQL、MongoDB、Redis）
• ORM（Prisma、Drizzle、SQLAlchemy）
• 身份验证方案（Auth.js、Clerk、自定义 JWT）
• 部署平台（Vercel、Railway、AWS）
• 按使用场景提供的技术栈建议（MVP、SaaS、企业级）

---

快速参考

技术栈决策矩阵

需求	建议
SEO 至关重要的网站	使用带 SSR 的 Next.js
内部仪表板	React + Vite
API 优先的后端	FastAPI 或 Fastify
企业级规模	NestJS + PostgreSQL
快速原型	Next.js API 路由
以文档为主的数据	MongoDB
复杂查询	PostgreSQL

常见问题

问题	解决方案
N+1 查询	使用 DataLoader 或预加载
构建缓慢	检查包体积，采用延迟加载
身份验证复杂	使用 Auth.js 或 Clerk
类型错误	在 tsconfig 中启用严格模式
CORS 问题	正确配置中间件

---

假设与可验证的成功标准（Karpathy 规范）

在此技能搭建、推荐或修改任何代码之前，必须明确以下四项假设。如果有任何一项未知，此技能将停止，并引导用户使用强制提问库。

1. 当前团队规模 + 未来 12 个月的人员规模 — 决定架构（单体 / 模块化 / 服务）。Sam Newman：“单体优先。”
2. 目标部署频率 — 决定 CI/CD 投入和功能标志投入。Accelerate（Forsgren 等，2018 年）。
3. 面向用户 / 内部使用 / 营销网站 — 决定技术栈选择以及无障碍性/性能预算。
4. 每月云服务 + SaaS 预算上限 — 决定自建与托管服务之间的取舍。

可验证的成功标准（Karpathy 第 4 条）——此技能给出的每项建议都必须包含三个可由机器检查的数值：

• API 延迟目标（p50、p95、p99，单位为 ms）
• 前端性能目标（移动 4G 网络下的 LCP、INP、CLS）
• 正常运行时间 / SLO 目标

如果没有明确写出这三项中的任何一项，该建议就不完整——返回强制提问库的 Q7。

tools scripts/fullstack_decision_engine.py 会编码这些检查：如果没有提供全部四项假设输入，它将拒绝推荐配置，并打印与匹配配置对应的可验证阈值。

---

自定义配置文件

profiles/ 中的四个内置配置文件会校准每条建议：

配置文件	适用场景	云支出上限	模式
saas-startup	工程人员少于 10 人、面向客户、每天或更频繁地发布	$8K/mo	基于 Next.js + Postgres 的模块化单体
enterprise-scale	工程人员 50 人以上、受监管、每个 PR 都有门禁	$250K/mo	按领域划分的服务 + 平台团队
internal-tool	工程人员不超过 5 人、有身份验证限制、DAU 少于 100	$500/mo	优先使用 Retool；确有需要时采用精简的自定义技术栈
marketing-site	依赖 SEO、几乎没有写入操作	$200/mo	静态优先（Astro / 11ty / Next-static）

通过以下方式选择配置文件：

python scripts/fullstack_decision_engine.py \
  --team-size 6 --team-size-12mo 12 \
  --cadence daily --user-facing true --budget 5000 \
  --traffic-p99-rps 45 --data-sensitivity pii-only

工具会返回最匹配的配置文件、与次优方案的权衡（如果差距在 15% 以内）、技术栈建议、该配置文件应避免的反模式，以及指定审批人的审批链。此工具绝不会自动批准。

要添加自定义配置文件：将 profiles/saas-startup.json 复制到 profiles/<your-org>.json，调整 constraints 和 stack_recommendations 区块，然后重新运行。JSON 是自定义入口，无需修改代码。

---

组合映射

此技能不会重新实现 POWERFUL 级专家负责的范围，而是分派给他们。完整路由表请参见 references/composition_map.md。主要分派目标如下：

关注领域	分派至
API 契约评审	engineering/skills/api-design-reviewer/
数据库架构设计	engineering/skills/database-designer/
可靠性 / SLO 设计	engineering/slo-architect/
CI/CD 流水线	engineering/skills/ci-cd-pipeline-builder/
性能分析	engineering/skills/performance-profiler/
提交前的 Karpathy 评审	engineering/karpathy-coder/
架构预检审查	engineering/grill-me/

cs-fullstack-engineer Agent（位于 agents/engineering/cs-fullstack-engineer.md）通过 context: fork 协调这些分派。可从其他 Agent 调用它：Agent({subagent_type: "cs-fullstack-engineer", prompt: "..."})；也可通过斜杠命令 /cs-fullstack-review <your problem> 调用。

---

逼问问题库（Matt Pocock 深度审查）

在敲定任何架构或技术栈决策前，请逐一回答 references/forcing_questions.md 中的七个逼问问题。每个问题都包含建议答案、规范引用和否决标准。执行时应遵守以下要求：

1. 每轮只问一个问题，不要打包提问。
2. 始终给出有规范依据的建议答案。
3. 在工作文件中跟踪答案（例如 /tmp/fullstack-grill-<date>.md）。
4. 如果触发否决标准，则停止。不要绕过尚未解决的问题继续搭建。
5. 回答完第 7 题后，将七个答案作为输入运行 fullstack_decision_engine.py。

七个问题概述（完整内容见参考文档）：

1. 当前团队规模和 12 个月后的人员规模是多少？
2. 部署频率是每个 PR、每天、每周还是每季度？
3. 是面向客户、内部工具还是营销网站？
4. 未来一年的 p50 / p99 流量预测是多少？
5. 是招聘熟悉该技术栈的人，还是培训团队？
6. 第一年每月云服务 + SaaS 的支出上限是多少？
7. 三项可验证的成功标准及其数值目标是什么？

---

从其他 Agent 和技能调用

其他任何 Agent 或技能都可以通过以下三种方式调用此技能：

1. 斜杠命令： /cs-fullstack-review <prompt> — 运行完整的深度审查、决策引擎和组合路由流程。
2. Agent 子 Agent： Agent({subagent_type: "cs-fullstack-engineer", prompt: "..."}) — 分叉上下文，并返回不超过 200 个单词的摘要。
3. 直接调用工具： python scripts/fullstack_decision_engine.py ... — 不经对话式深度审查，确定性地匹配配置文件（输入已知时使用）。

完整的调用约定请参见 agents/engineering/cs-fullstack-engineer.md。