4.3 KiB
4.3 KiB
NEX 0.1.6 — 新项目快速开始(带默认技术栈)
1. 放置规范包
建议目录:
project-root/
├── AGENTS.md
├── nex.config.yaml
├── standards/
│ └── nex-design-system/
├── docs/
└── frontend/ / backend/ # 由项目类型和默认技术栈初始化
将 ZIP 内 NEX-Design-System-v0.1.6/ 的内容放入 standards/nex-design-system/。
2. 复制默认配置
将 standards/nex-design-system/config/project-profile.example.yaml 复制到项目根目录,命名为 nex.config.yaml。
默认技术栈已经给定,不需要从零填写:
- 前端:React + TypeScript + Vite + Ant Design + Tailwind CSS v4 + Zustand + React Router + Axios。
- 后端:Python + FastAPI + Pydantic + SQLAlchemy + Alembic。
- 数据库:开发 SQLite,生产 PostgreSQL。
- API:REST + OpenAPI。
- 本地资源:
./data。 - 质量工具:ESLint、Prettier、Vitest、Playwright、Pytest。
这些是 NEX 新项目的默认起步方案。需要不同技术时,只修改 YAML 中对应字段,不必填写整份技术清单。
生命周期如何处理
project.lifecycle 默认为 auto:
- 空仓库/无应用代码:按新项目处理,使用上述默认技术栈。
- 已有代码、锁文件或构建配置:按已有项目处理,自动识别并保留当前技术栈,不会强行改成默认方案。
如果需要明确指定,可将其改为 new 或 existing。
项目类型
默认 project.type: fullstack。纯前端项目只需改为 frontend-only;纯后端项目改为 backend-only。Agent 不应初始化不适用的部分。
3. 合并根 AGENTS.md
不要覆盖项目已有的根 AGENTS.md。合并以下规则,并按实际安装路径调整:
## NEX Design System
本项目采用 NEX Design System 0.1.6 作为跨项目设计治理标准。
规范位于 `standards/nex-design-system/`。
UI/UX 任务开始前,读取 NEX AGENTS.md、docs/00-governance-and-adaptation.md、
docs/09-agent-execution-rules.md、docs/12-responsive-accessibility-quality.md、
docs/13-project-stack-defaults.md、docs/14-accessibility-platform-matrix.md,以及项目根目录 nex.config.yaml。
新项目按 nex.config.yaml 中的 stack 默认值初始化,不得忽略或自行替换技术选型。
已有项目自动识别实际技术栈并保留,不得因默认值不同而迁移。
先审计、建立符合性矩阵、提交计划;未经授权不得全量重构或自动进入下一阶段。
4. 首次交给 Agent
将 templates/new-project-audit-prompt.md 交给 Agent。
- 新项目:先核对默认技术栈与项目类型,给出目录结构、依赖和初始化计划;本轮只审计,不实际创建业务代码,除非你另行授权。
- 已有项目:从锁文件、源码、构建配置和运行结果识别真实技术栈,形成与 NEX 的差异映射;不得把默认栈当作迁移目标。
5. 只修改真正需要覆盖的字段
例如,若希望数据库从“开发 SQLite、生产 PostgreSQL”改为两阶段均 PostgreSQL,只修改:
stack:
database:
development: PostgreSQL
production: PostgreSQL
如希望纯前端项目,只修改:
project:
type: frontend-only
其余默认项保持不动。审计报告不是代码修改授权;确认实施范围后再让 Agent 开始开发。
6. 无障碍测试怎么执行
- 默认工程目标为 WCAG 2.2 AA;日常验收使用源码审阅、Playwright/axe 等自动化和浏览器键盘交互(E0–E2)。
- 真实屏幕阅读器(E3)仅在复杂自定义交互、关键业务流程、Live Region、复合控件或客户/法规要求等风险条件下触发,不是每次提交的必做步骤。
- 按项目目标平台选择 AT:macOS VoiceOver、Windows NVDA(必要时 JAWS/Narrator)、Linux Orca。项目不承诺的平台不强制加入测试矩阵。
- Agent 不得自动启动或关闭系统屏幕阅读器;启动/关闭前必须取得本次 E3 测试的明确授权。
- 目标环境不可用时,若 E3 已判定必要,标记
MANUAL_QA_REQUIRED;若风险评估不需要 E3,记录E3_NOT_REQUIRED。
详见 docs/08-accessibility-responsive.md、docs/12-responsive-accessibility-quality.md 和 docs/14-accessibility-platform-matrix.md。