{"id":31965225,"url":"https://github.com/atorber/doc-first","last_synced_at":"2026-02-18T03:03:23.184Z","repository":{"id":315626241,"uuid":"1060270041","full_name":"atorber/doc-first","owner":"atorber","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-25T06:09:35.000Z","size":4474,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-27T21:53:57.356Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atorber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T16:29:54.000Z","updated_at":"2025-11-25T06:09:38.000Z","dependencies_parsed_at":"2025-09-19T18:46:09.869Z","dependency_job_id":"f81b0577-9341-4253-a704-535677c2fcdc","html_url":"https://github.com/atorber/doc-first","commit_stats":null,"previous_names":["atorber/doc-first"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/atorber/doc-first","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atorber%2Fdoc-first","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atorber%2Fdoc-first/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atorber%2Fdoc-first/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atorber%2Fdoc-first/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atorber","download_url":"https://codeload.github.com/atorber/doc-first/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atorber%2Fdoc-first/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29566676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"online","status_checked_at":"2026-02-18T02:00:09.468Z","response_time":162,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T17:53:43.056Z","updated_at":"2026-02-18T03:03:23.155Z","avatar_url":"https://github.com/atorber.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DOC FIRST\n\n## 文档优先的原生氛围编程（Vibe Coding）最佳实践\n\n基于\"文档工具+CLI+AI IDE\"实现从需求文档出发到工程实现的端到端开发流程\n\n---\n\n## 🎯 核心理念\n\n**文档即代码，文档即产品** - 通过结构化的文档驱动整个开发流程，让每个环节都有清晰的输入输出，实现真正的\"文档优先\"开发模式。\n\n- 文档库：需要一个云端文档管理工具，可以是飞书文档、语雀等提供API接口的在线文档\n- AI IDE：qoder、trae、cursor等\n- 前后端框架：ant-design-pro + python、typescript\n\n---\n\n## 最佳实践\n\n### 准备工作\n\n下载项目选择的模板项目到本地\n\n前端推荐使用 [ant-design-pro](https://github.com/ant-design/ant-design-pro)\n\n```\ngit clone https://github.com/ant-design/ant-design-pro.git\n```\n\n后端可以使用任何自己熟悉语言的框架或已有项目\n\n### 📂 项目结构规范\n\n创建项目目录，然后规划各子目录，以下只是一个建议，可以根据自己的习惯组织，清晰的目录结构有助于最终的代码组织\n\n以下是经过验证的标准项目结构方案，建议开发者按此规范组织代码（可根据项目规模适当调整）：\n\n```bash\n├── 📁 docs/                    # 项目文档中心\n│   ├── requirements/          # 需求文档（用户故事/功能需求/验收标准）\n│   ├── designs/               # 设计文档（架构图/API设计/DB设计）\n│   └── references/            # 第三方API文档/技术参考资料\n\n├── 📁 backend/                # 后端服务（以Python为例）\n│   ├── src/                   # 核心代码\n│   ├── config/                # 环境配置\n│   └── tests/                 # 单元测试 \u0026 E2E测试\n\n├── 📁 frontend/               # 前端工程（基于 Ant Design Pro）\n│   ├── config/                # 项目配置\n│   ├── mock/                  # 本地Mock数据\n│   └── src/                   # 页面组件与业务逻辑\n│   └── ...                    # 其他目录和文件\n\n├── 📁 sdk/                    # 第三方服务SDK\n│   ├── payment/               # 支付服务封装\n│   ├── cloud-storage/         # 云存储服务\n│   └── social-login/          # 社交登录集成\n\n├── 📄 README.md               # 项目门户文档（需包含：快速开始/环境要求/部署指南）\n└── 📄 CHANGELOG.md            # 版本更新日志\n```\n\n#### 文档规范\n1. **文档管理**：所有文档必须使用 Markdown 格式，遵循「文档即代码」原则\n2. **版本同步**：需求文档与代码实现保持版本对应（通过 git tag 关联）\n3. **协作规范**：设计文档需包含决策记录（ADR）和架构图例\n\n### vibe coding\n\n开始你的vibe coding之旅...\n\n## 🚀 完整开发流程\n\n### 1. 需求文档 (Requirements Documentation)\n**目标**: 明确产品目标和用户需求\n\n#### 1.1 用户故事 (User Stories)\n- 使用 Markdown 格式编写用户故事\n- 包含：角色、功能、价值三个要素\n- 示例：\n  ```markdown\n  ## 用户故事\n  - 作为用户，我希望能够快速搜索产品，以便找到我需要的商品\n  - 作为管理员，我希望能够管理用户权限，以便控制系统访问\n  ```\n\n#### 1.2 功能需求 (Functional Requirements)\n- 详细描述每个功能模块\n- 包含输入、处理、输出描述\n- 使用表格形式整理优先级\n\n#### 1.3 非功能需求 (Non-functional Requirements)\n- 性能要求\n- 安全要求\n- 可用性要求\n- 兼容性要求\n\n### 2. 设计文档 (Design Documentation)\n**目标**: 将需求转化为技术实现方案\n\n#### 2.1 系统架构设计\n- 整体架构图 (使用 Mermaid 或 PlantUML)\n- 技术栈选择\n- 模块划分和依赖关系\n\n#### 2.2 数据库设计\n- ER 图设计\n- 表结构定义\n- 索引和约束设计\n\n#### 2.3 API 设计\n- RESTful API 规范\n- 请求/响应格式定义\n- 错误码和状态码规范\n\n#### 2.4 安全设计\n- 认证授权机制\n- 数据加密策略\n- 安全漏洞防护\n\n### 3. 视觉交互 (Visual \u0026 Interaction Design)\n**目标**: 定义用户界面和交互体验\n\n#### 3.1 设计系统\n- 色彩规范\n- 字体规范\n- 组件库定义\n- 图标系统\n\n#### 3.2 原型设计\n- 线框图 (Wireframes)\n- 高保真原型\n- 交互流程图\n\n#### 3.3 响应式设计\n- 移动端适配\n- 平板端适配\n- 桌面端适配\n\n### 4. 前后端实现 (Frontend \u0026 Backend Implementation)\n**目标**: 将设计转化为可运行的代码\n\n#### 4.1 开发环境搭建\n- 项目初始化\n- 依赖管理\n- 开发工具配置\n\n#### 4.2 后端开发\n- API 实现\n- 数据库操作\n- 业务逻辑实现\n- 单元测试\n\n#### 4.3 前端开发\n- 组件开发\n- 状态管理\n- 路由配置\n- 样式实现\n\n#### 4.4 集成测试\n- API 集成测试\n- 端到端测试\n- 性能测试\n\n---\n\n## 🛠️ 推荐工具链\n\n### 文档工具\n- **Notion** - 协作式文档编辑\n- **Obsidian** - 知识图谱式文档管理\n- **GitBook** - 技术文档发布\n- **Mermaid** - 图表绘制\n\n### CLI 工具\n- **create-react-app** / **Vite** - 前端项目初始化\n- **Express Generator** / **Nest CLI** - 后端项目初始化\n- **Prisma** - 数据库 ORM\n- **Docker** - 容器化部署\n\n### AI IDE\n- **Cursor** - AI 驱动的代码编辑器\n- **GitHub Copilot** - AI 代码助手\n- **Tabnine** - 智能代码补全\n\n---\n\n## 📋 文档模板\n\n### 需求文档模板\n```markdown\n# 项目需求文档\n\n## 项目概述\n- 项目名称：\n- 项目目标：\n- 目标用户：\n\n## 功能需求\n### 核心功能\n1. 功能名称\n   - 描述：\n   - 优先级：高/中/低\n   - 验收标准：\n\n## 非功能需求\n- 性能要求：\n- 安全要求：\n- 可用性要求：\n```\n\n### 设计文档模板\n```markdown\n# 系统设计文档\n\n## 架构设计\n### 整体架构\n```mermaid\ngraph TB\n    A[前端] --\u003e B[API Gateway]\n    B --\u003e C[业务服务]\n    C --\u003e D[数据库]\n```\n\n## 技术选型\n- 前端：React + TypeScript\n- 后端：Node.js + Express\n- 数据库：PostgreSQL\n```\n\n---\n\n## 🎯 最佳实践\n\n### 1. 文档版本控制\n- 使用 Git 管理文档版本\n- 建立文档审查流程\n- 保持文档与代码同步\n\n### 2. 迭代式开发\n- 每个迭代都从更新文档开始\n- 文档变更需要团队评审\n- 定期回顾和优化文档结构\n\n### 3. 自动化集成\n- 文档自动生成 API 文档\n- 代码注释自动同步到文档\n- 持续集成中集成文档检查\n\n### 4. 团队协作\n- 建立文档编写规范\n- 定期进行文档评审\n- 鼓励团队成员贡献文档\n\n---\n\n## 📚 相关资源\n\n- [文档驱动开发指南](https://example.com)\n- [API 设计最佳实践](https://example.com)\n- [前端组件设计系统](https://example.com)\n- [后端架构设计模式](https://example.com)\n\n---\n\n## 🤝 贡献指南\n\n欢迎提交 Issue 和 Pull Request 来改进这个文档优先的开发流程！\n\n1. Fork 本仓库\n2. 创建特性分支\n3. 提交更改\n4. 发起 Pull Request\n\n---\n\n*最后更新：2024年*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatorber%2Fdoc-first","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatorber%2Fdoc-first","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatorber%2Fdoc-first/lists"}