team/CLAUDE.md

• Always reply in Chinese

ISOS Agent Teams 软件研发模板

通用 Agent Teams 软件研发项目模板，支持多角色 AI Agent 并行协作开发。

完整项目规范见 .claude/CLAUDE.md

目录结构

apps/
├── server/     # 服务端应用 (FastAPI + SQLite)
├── desktop/    # 桌面端应用 (PyWebView + Svelte + SQLite)
docs/           # 项目文档
specs/          # speckit 功能规格
.specify/       # speckit 配置
memory/        # 跨会话记忆（经验、偏好、历史）

模块独立性: 各模块完全独立，禁止跨模块代码引用，仅通过 API 通信。

核心约束

• 语言: Python 3.12+ / TypeScript (前端)
• 框架: FastAPI (服务端) + Svelte 5 + PyWebView (桌面端)
• 数据库: SQLite 3.45+
• 包管理: uv（Python）/ nvm + npm（前端）
• 版本控制: Jujutsu (jj)，主分支 trunk
• 提交类型: 必须使用中文（功能、修复、维护...），详见 team/git.md

技术栈

以下为推荐技术栈，具体项目可根据需求调整。

组件	技术	约束
语言	Python 3.12+	强制
包管理	uv	强制
服务端	FastAPI	推荐
桌面端	PyWebView + Svelte 5	推荐
数据库	SQLite 3.45+	推荐
容器化	Docker	服务端推荐

关键架构约束

• 模块独立: apps/server 和 apps/desktop 各有独立的 .venv、uv.lock、pyproject.toml。禁止跨模块代码引用，仅通过 API 通信
• 每个 PR 只能改动一个模块（server 或 desktop），标题格式：[模块] 描述

命令（必须 cd 到对应 app 目录执行）

# 服务端 (cd apps/server)
uv run mypy src/ --strict        # 类型检查
uv run pytest                    # 测试
ruff format --check . && ruff check .  # 代码质量

# 桌面端 (cd apps/desktop)
uv run mypy src/ --strict        # 类型检查
uv run pytest                    # 测试
ruff format --check . && ruff check .  # 代码质量

编码规范

格式化

• 缩进: 4 空格 | 行长度: 100 字符
• 格式化: ruff format | Lint: ruff check

命名约定

• PascalCase: 类名、类型、异常
• snake_case: 函数、方法、变量、模块
• UPPER_SNAKE_CASE: 常量

类型注解

• 必须使用完整类型注解，mypy strict 模式
• 禁止使用 Any 类型

注释规范

• 使用 Google 风格 docstring
• 公共函数和类必须有文档字符串

字符串规范

• 用户可见字符串：双引号 | 代码内部：单引号

Svelte 开发

完整指南见 team/svelte.md。核心流程：

1. list-sections → get-documentation → 编码 → svelte-autofixer 验证
2. .svelte 文件优先使用 svelte-file-editor 子代理

开发工作流

speckit 集成

/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement

版本控制

• 版本控制: Jujutsu (jj)，并存模式（.jj + .git 并存）
• 分支: Trunk-Based Development，主分支 trunk
• 提交类型: 使用中文类型（功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并），完整列表见 team/git.md

关键文档

文档	用途
.claude/CLAUDE.md	完整编码规范、模块说明、验证步骤
docs/01-用户需求.md	用户需求、项目目标、验收标准
docs/03-功能列表.md	功能需求（FR）列表
docs/02-产品需求.md	非功能性需求、约束
docs/05-设计-UI.md	UI 界面设计
docs/06-设计-UX.md	用户体验设计
team/git.md	Git 提交规范、分支策略
team/jj.md	jj 命令对照表
team/svelte.md	Svelte 5 开发完整指南
team/tmux.md	tmux 团队协作规范