istofel/istofel-project-plan

---

# Istofel 项目计划 一个专业的 Claude 技能，引导你完成完整的产品规划过程——从原始想法到可实现的文档，共分为四个结构化步骤：**MVP 范围 → PRD → SPEC → CLAUDE.md**。 每个文档会逐一生成。Claude 会在进入下一步之前请求你的确认，确保你在继续之前审查并批准每个阶段。 ## 作用 给定一个产品想法，该技能会生成四个专业的技术文档： | 文档 | 目的 | |------|------| | **MVP 范围** | 市场研究、竞争格局、推荐技术栈、架构概览、数据模型预览、业务规则、盈利模式、功能路线图与风险 | | **PRD** | 设计原则、人物角色与用例地图、功能需求（带类型化业务规则）、UI 状态、ASCII 布局、用户流程、功能规格说明、数据模式、冲刺路线图与全局验收标准 | | **SPEC** | ADR、模块级技术规格（含类型签名）、关键逻辑、状态机、领域不变性、构建顺序与检查点、序列图、数据库模式与约束、API 合约、错误层级、安全检查清单、可观测性、测试策略与 CI/CD 流水线 | | **CLAUDE.md** | 为个人 AI 代理准备的上下文文件——自动从前三份文档中提取栈、ADR、不变性、构建顺序、禁止操作与术语表，可直接放入项目仓库 | ## 安装 ### 1. 克隆仓库 ``` git clone https://github.com/istofel/istofel-project-plan.git cd istofel-project-plan ``` ### 2. 下载 ZIP 包 在仓库页面点击 **Code → Download ZIP**。 ### 3. 在 Claude 中安装 1. 打开 [Claude.ai](https://claude.ai) 或 Claude Code 2. 进入 **Settings → Skills** 3. 点击 **Upload a skill** 4. 选择已下载的 ZIP 文件 **istofel-project-plan-main.zip**（路径：`istofel-project-plan/`） ## 使用方法 ### 第一步：从你的想法开始 通过描述你的产品来触发该技能。你可以提供简要或详细的描述。如果缺少关键信息，技能会提出澄清问题。 **示例提示：** ``` I want to build a mobile app that helps freelancers track their working hours and generate invoices automatically. Target users are designers and developers who work for multiple clients. I want to charge a monthly subscription. ``` **或者仅输入：** ``` Help me plan a SaaS for restaurant inventory management. ``` 如果缺少关键信息（目标用户、盈利模式、分发平台、技术约束），Claude 最多会提出 5 个聚焦问题，然后生成 MVP 范围。 --- ### 第二步：审查 MVP 范围 Claude 会生成完整的 MVP 范围文档，涵盖： - 产品愿景与价值主张 - 市场规模与竞争格局 - 推荐技术栈（含权衡分析） - 架构概览（ASCII 图） - 数据模型预览 - 核心业务规则 - 功能路线图（核心 MVP / 发布后 v1 / 未来） - 盈利模式 - 风险与不包含的内容 - 执行摘要 审查完成后，Claude 会询问： 回复 **yes** 继续，或先提出修改请求。 --- ### 第三步：审查 PRD Claude 会生成完整的 PRD，包含： - 设计原则 - 人物角色与用例地图 - 功能需求（含验收标准、类型化业务规则与错误处理） - 非功能性需求 - 主界面的 ASCII 布局 - 屏幕状态（离线、空、加载、错误、就绪） - 用户流程（类伪流程图，如 onboarding、happy path 等） - 功能规格说明（含组件、类型化规则与 MVP 限制） - 完整数据模式（含索引与迁移策略） - 冲刺路线图 - 全局验收标准（完成度的二元定义） - 风险、不包含内容与术语表 审查完成后，Claude 会询问： ### 第四步：审查 SPEC Claude 会生成完整的 SPEC，包含： - **ADRs（架构决策记录）**——每个重要技术决策均记录上下文、决策、理由与影响；代理将 ADR 视为已关闭决定，不再重新讨论 - 带层级与协议的架构图 - 项目目录树及每个文件的职责说明 - 全局常量与环境变量 - 模块级规格（含类型签名、关键逻辑、框架说明） - 会话状态文档 - 完整的 SQL 模式（含 CHECK 约束与迁移策略） - **状态机与领域不变性**——对具有复杂生命周期的实体，记录状态转移、副作用、终止状态以及四种不变性（不变性、验证、状态转移、授权） - **构建顺序**——编号的线性步骤，包含具体实现项与强制检查点；代理在确认前一步有效之前不会进入下一步 - API 合约（内部端点与所消费的外部 API） - 错误层级与每种异常类型的 UI 处理方式 - 安全检查清单（输入净化、速率限制、密钥管理） - 可观测性（日志格式、指标、告警） - 测试策略（含测试夹具、关键测试、覆盖率目标） - 关键流程的序列图 - CI/CD 流水线与部署环境 审查完成后，Claude 会询问： ### 第五步：审查 CLAUDE.md Claude 会自动生成个性化的 `CLAUDE.md` 文件——无需进一步提问。所有信息均从前三份文档中提取。 生成的 `CLAUDE.md` 包含： - **项目概述**——名称、一句话描述、所用技术栈、前三份文档的引用 - **必须遵循的代码模式**——语言约定、数据库访问模式、认证模式、错误处理 - **永远不要做的事**——从 ADR 与授权规则中提取的明确禁止列表 - **固定的技术栈与版本**——附带 ADR 引用；代理将这些视为已关闭决定 - **目录结构**——明确说明每种文件应创建的位置 - **关键领域不变性**——所有 INV-XX 及其在代码中验证的位置 - **构建顺序**——从 SPEC 复制，并带有当前步骤字段，供开发者跟踪进度 - **环境变量**——从 SPEC 常量部分提取 - **已解答的边缘情况**——从 PRD 提取，防止错误实现 - **领域术语表**——在代码、日志与注释中保持一致的术语 将 `CLAUDE.md` 放入项目仓库的根目录。Claude Code 会在每个会话开始时自动加载它。 --- ## 获取最佳效果的建议 ### 提前提供上下文 你提供的上下文越充分，Claude 提出的澄清问题就越少。理想输入应包括： | 信息 | 示例 | |------|------| | **功能描述** | “一个完全离线的本地 AI 助手” | | **目标用户** | “注重隐私的 Python 开发者” | | **核心问题** | “现有工具依赖云 API 或 Docker” | | **分发方式** | “通过 pip 安装、桌面应用、Web SaaS、移动端” | | **盈利模式** | “开源免费 + 增值服务 + 月度订阅” | | **技术约束** | “必须使用 Python、团队 1 人、无付费基础设施” | | **关键特性** | “聊天、文件上传、对话历史、指标监控” | ### 审查后再继续 每个文档都建立在前一个之上。如果 MVP 范围中的技术栈或目标用户有误，会传播到 PRD、SPEC 和 CLAUDE.md。请花时间审查每一步。 ### 在继续前提出修改请求 你可以要求 Claude 在确认前修改任意部分。例如： ``` Before we move to the PRD, please revise the tech stack section — I want to use FastAPI instead of Django, and PostgreSQL instead of SQLite. ``` --- ### 技能会标记你遗漏的内容 在整个文档过程中，Claude 会主动用以下标记提示被忽略但重要的内容： 这些包括：数据保留策略、LGPD/GDPR 合规性、可观测性设置、国际化（i18n）、可访问性（WCAG）、测试策略、许可定义、回滚策略（针对第三方依赖）。 --- ## 文档示例 ### MVP 范围——节选 ``` ## 3. 推荐技术栈 | Layer | Choice | Alternative | Trade-off | |-------------|----------------|---------------|------------------------------------------------| | Backend | FastAPI | Django | FastAPI is lighter and async-native; Django has more batteries | | Database | SQLite | PostgreSQL | SQLite needs zero infra; migrate to Postgres at 10k+ users | | Auth | JWT (PyJWT) | Auth0 | JWT is self-contained; Auth0 adds cost but saves implementation time | | Deploy | Railway | Fly.io | Railway is simpler for solo devs; Fly gives more control | **Premise:** Single-developer team. No existing infrastructure. ## 9. 功能路线图 | Feature | Priority | Complexity | Dependencies | |----------------------|----------------|------------|------------------| | User auth (JWT) | Essential MVP | Medium | — | | Dashboard overview | Essential MVP | Medium | Auth | | Invoice generation | Essential MVP | High | Dashboard | | PDF export | Post-MVP v1 | Medium | Invoice | | Stripe integration | Post-MVP v1 | High | Invoice | | Mobile app | Future | High | API stable | ``` --- ### PRD——节选 ``` ## RF-03: 发票生成 **Description:** The system must allow users to generate invoices from tracked time entries. **Acceptance criteria:** - User selects a client and a date range - System calculates total hours and applies the configured hourly rate - Invoice is rendered with line items, subtotal, taxes, and total - User can edit line items before finalizing - Finalized invoice receives a sequential number and is locked for editing **Rules:** - Hourly rate defaults to the client's configured rate; can be overridden per invoice | Type: Validation - Tax rate is configured per user account (default: 0%) | Type: Invariant - Invoice number format: `INV-{YEAR}-{SEQUENCE}` (e.g., INV-2026-0042) | Type: Invariant - Only the invoice owner can delete a draft invoice | Type: Authorization - Invoice transitions from `draft` to `finalized` when the user confirms; once finalized, editing is locked | Type: State Transition **Error handling:** - No time entries in selected range → show empty state with CTA to log hours - Client has no hourly rate configured → show inline warning before generation --- ## 6.3 屏幕状态 | State | Trigger | What appears | |------------|----------------------------|---------------------------------------------------| | Empty | No invoices yet | Illustration + "Generate your first invoice" CTA | | Loading | Fetching invoice list | Skeleton rows | | Ready | Data loaded | Invoice list with filters | | Error | API failure | Banner: "Could not load invoices. Try again." | ``` --- ### SPEC——节选 ``` ## 2. ADRs — 架构决策记录 ADR-01: FastAPI as backend framework Context: Need async-native Python framework; team is familiar with Python. Evaluated Django REST Framework and Flask. Decision: FastAPI over Django REST Framework. Rationale: Native async support, automatic OpenAPI docs, Pydantic validation built-in. Django adds ORM and admin overhead not needed here. Consequences: Follow FastAPI dependency injection patterns. Do not use Django ORM or Flask blueprints. --- ## 8. 状态机和领域不变式 ### 发票 — 状态机 States: draft | finalized | cancelled Transitions: draft ── user confirms ──→ finalized side effect: invoice number assigned, editing locked draft ── user discards ──→ cancelled side effect: line items soft-deleted Terminal states: cancelled — no further transitions allowed ### 领域不变式 INV-01: [Invariant] A finalized invoice always has a non-null, unique invoice number. Verify in: invoice repository save() — assert before commit INV-02: [Validation] An invoice can only be finalized if it has at least one line item with hours > 0. Verify in: InvoiceService.finalize() — check before state transition INV-03: [Authorization] Only the invoice owner or an admin can cancel a finalized invoice. Verify in: authorization middleware — before reaching InvoiceService ``` --- ### CLAUDE.md——节选 ``` # CLAUDE.md — InvoiceApp ## 1. 项目概述 Product: InvoiceApp — freelancer time tracking and invoice generation Stack: Python 3.12 + FastAPI + SQLite + PyJWT Docs: docs/mvp-scope.md · docs/prd.md · docs/spec.md ## 3. 绝不能做的事 - NEVER create an auth system from scratch — use PyJWT per ADR-02 - NEVER expose API keys or secrets in code — always via environment variables - NEVER use SELECT * — always specify fields - NEVER allow editing a finalized invoice — INV-01 prohibits it - NEVER advance to the next build step without confirming the checkpoint ## 6. 关键领域不变式 INV-01: [Invariant] A finalized invoice always has a non-null unique number. Verify in: InvoiceRepository.save() — assert before commit INV-02: [Validation] Invoice can only be finalized with at least one line item with hours > 0. Verify in: InvoiceService.finalize() — before state transition INV-03: [Authorization] Only owner or admin can cancel a finalized invoice. Verify in: authorization middleware — before InvoiceService ## 7. 构建顺序 STEP 1: Project setup — checkpoint: app starts, linter passes STEP 2: Database and migrations — checkpoint: tables created, idempotent STEP 3: Core business logic — checkpoint: invariant tests pass, 80% coverage Current step: 1 ``` --- ## 仓库结构 ``` istofel-project-plan/ ├── SKILL.md # Main skill logic, flow, triggers, proactive rules └── references/ ├── mvp-scope.md # Complete MVP Scope structure and checklist ├── prd.md # Complete PRD structure and checklist ├── spec.md # Complete SPEC structure and checklist (21 sections) └── claude-md.md # CLAUDE.md generation rules and structure ``` --- ## 许可证 MIT 许可证——版权所有 (c) 2026 Vinícius Istofelira。 请参见 [LICENSE](LICENSE) 获取完整文本。

标签：API 设计, API集成, Claude 技能, MoSCoW 优先级, MVP, PRD, SEO, SQL 架构, 主动建议系统, 产品规划, 分析, 前端规范, 可观测性, 合规, 后端开发, 安全, 技术规格, 数据模型, 文档自动化, 权限管理, 架构设计, 模型越狱, 测试用例, 测试策略, 用户流程, 质量检查清单, 超时处理, 逆向工具, 领域驱动设计