isos/team

Fork 0

Files

arno 34346be862

CI / lint (push) Successful in 6s

Details

配置: 初始化 ISOS Agent Teams 软件研发模板

2026-04-19 21:47:08 +08:00

5.1 KiB

Raw Permalink Blame History

开发入门

文档版本: 1.0.0 最后更新: 2026-04-19

1. 项目概览

技术栈

组件	技术
语言
框架
数据库
版本控制	Jujutsu (jj)
包管理	uv（Python）/ nvm + npm（前端）

核心架构约束

模块独立性：各模块完全独立，禁止跨模块代码引用
通信方式：仅通过 REST API

2. 快速开始

2.1 环境搭建

完整的环境搭建指南见 管理-开发环境搭建.md。核心步骤：

# 1. 克隆仓库
jj git clone <!-- 仓库地址 -->
cd <!-- 项目目录 -->

# 2. 安装依赖
cd apps/<!-- 模块 --> && uv sync && cd ../..

2.2 验证安装

# <!-- 模块 -->
cd apps/<!-- 模块 -->
uv run python -c "from <!-- 模块名 -->.main import app; print('OK')"

3. 项目结构

<!-- 项目名 -->/
├── apps/
│   ├── <!-- 模块1 -->/          # <!-- 说明 -->
│   │   ├── src/<!-- 模块名 -->/
│   │   │   ├── main.py
│   │   │   ├── api/
│   │   │   ├── services/
│   │   │   ├── models/
│   │   │   └── db/
│   │   ├── tests/
│   │   └── pyproject.toml
│   │
│   └── <!-- 模块2 -->/          # <!-- 说明 -->
│       └── ...
│
├── docs/                           # 项目文档
├── specs/                          # 功能规格
├── team/                          # 团队公共知识
└── .claude/                        # Claude Code 配置

模块边界

规则	说明
禁止跨模块引用	各模块之间不能 import
仅通过 REST API 通信
独立数据库	各模块有独立数据库，Schema 版本独立递增
独立依赖	各模块有独立 `pyproject.toml`

4. 开发工作流

4.1 speckit 功能开发流程

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

4.2 版本控制

项目使用 Jujutsu (jj)，并存模式：

# 日常开发
jj new trunk                    # 在 trunk 上新建工作副本
# ... 编写代码 ...
jj diff                         # 查看变更
jj describe -m "功能: 添加xxx"  # 设置提交消息
jj new                          # 固化当前提交

# 推送到远程
jj b c feature-xxx              # 创建书签
jj git push -b feature-xxx      # 推送

完整 jj 命令对照表见 team/jj.md，Git 提交规范见 team/git.md。

提交类型（中文）：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并、回滚

4.3 PR 规范

每个 PR 只能改动一个模块
标题格式：[模块] 描述
主分支：trunk（Trunk-Based Development）

5. 常用命令

# 类型检查
uv run mypy src --strict

# 运行测试
uv run pytest

# 代码质量
ruff format --check . && ruff check .

# 格式化
ruff format .

# Lint 自动修复
ruff check . --fix

6. 代码质量

编码规范

规范项	规则
缩进	4 空格
行长度	100 字符
命名	PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量
类型注解	mypy strict，禁止 `Any`
Docstring	Google 风格，公共 API 必须有
字符串	用户可见用双引号，代码内部用单引号

质量门禁

ruff format --check .    # 格式检查
ruff check .             # Lint 检查
uv run mypy --strict      # 类型检查
uv run pytest             # 测试通过

7. 测试

测试策略

详见 10-测试-方案.md 和 测试-计划.md。

测试文件组织

apps/<!-- 模块 -->/tests/
├── unit/              # 单元测试
├── integration/       # 集成测试
└── conftest.py        # 测试夹具

运行测试

# 全部测试
uv run pytest

# 仅单元测试
uv run pytest tests/unit/

# 带覆盖率
uv run pytest --cov=src --cov-report=term-missing

8. 文档体系

项目文档按类型分类，全部使用中文命名：

类别	前缀	示例
核心文档	`01-` ~ `12-`	`01-用户需求.md`
设计文档	`设计-`	`设计-Apple风格.md`
管理文档	`管理-`	`管理-开发入门.md`
运维文档	`运维-`	`运维-部署实施.md`
测试文档	`测试-`	`测试-方案.md`

完整索引见 README.md 和 CLAUDE.md。

版本历史:

v1.0.0 (2026-04-19): 初始化模板

5.1 KiB Raw Permalink Blame History Unescape Escape