{"id":48495477,"url":"https://github.com/opensourceways/agent-development-specification","last_synced_at":"2026-04-07T12:02:25.954Z","repository":{"id":342217889,"uuid":"1173245816","full_name":"opensourceways/agent-development-specification","owner":"opensourceways","description":"Specifications for development including team/project/personal three levels","archived":false,"fork":false,"pushed_at":"2026-03-23T02:16:53.000Z","size":131,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T22:31:04.375Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/opensourceways.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":"2026-03-05T06:45:53.000Z","updated_at":"2026-03-23T02:16:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/opensourceways/agent-development-specification","commit_stats":null,"previous_names":["opensourceways/agent-development-specification"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/opensourceways/agent-development-specification","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensourceways%2Fagent-development-specification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensourceways%2Fagent-development-specification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensourceways%2Fagent-development-specification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensourceways%2Fagent-development-specification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opensourceways","download_url":"https://codeload.github.com/opensourceways/agent-development-specification/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensourceways%2Fagent-development-specification/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31511785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-04-07T12:02:14.984Z","updated_at":"2026-04-07T12:02:25.909Z","avatar_url":"https://github.com/opensourceways.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude 开发规范体系\n\n本仓库定义了团队使用 Claude Code 进行协作开发时的**三层规范体系**，确保 AI 辅助开发在团队、项目、个人三个维度上保持一致性。\n\n---\n\n## 这个仓库是做什么的\n\n本仓库有两个核心用途：\n\n1. **`spec/` — 插件读取的实际规范内容**（团队级规范 + 项目模板，由 Claude Code 插件自动注入）\n2. **`specification-example/` — 参考示例**（展示各层规范文件应该长什么样，供人工参考和学习）\n\n\u003e 简单说：`spec/` 是\"用的\"，`specification-example/` 是\"看的\"。\n\n---\n\n## 三层架构总览\n\n```\nLayer 3 · 个人层        ~/.claude/CLAUDE.md\n                         ~/.claude/commands/          ← 个人专属命令（本机生效）\n                            ↓ 覆盖 / 扩展\nLayer 2 · 项目层        \u003cproject\u003e/CLAUDE.md\n                         \u003cproject\u003e/docs/standards/    ← 项目特有规范\n                         \u003cproject\u003e/.claude/commands/  ← 项目共享命令（提交仓库）\n                         \u003cproject\u003e/.claude/settings.json ← 项目 Hooks 配置\n                            ↓ 覆盖 / 扩展\nLayer 1 · 团队层        本仓库 spec/teams/\n                         CLAUDE.md\n                         docs/standards/              ← 团队规范文档\n                         .claude/commands/            ← 团队通用命令\n```\n\n**优先级：个人层 \u003e 项目层 \u003e 团队层**（下层是基础，上层可覆盖或扩展）\n\n---\n\n## 目录结构\n\n```\nREADME.md                                    # 本文件，体系总览\n│\n├── spec/                                        # ★ 插件读取的实际规范内容\n│   ├── teams/                                   # Layer 1：团队级规范（对所有项目生效）\n│   │   ├── CLAUDE.md                            # 团队 Claude 入口 + 工作约束\n│   │   └── docs/standards/                      # 团队规范文档\n│   │       ├── architecture.md\n│   │       ├── coding/base.md\n│   │       ├── coding/\u003clang\u003e.md\n│   │       ├── testing.md\n│   │       ├── security.md\n│   │       └── docs-writing.md\n│   └── project-templates/                       # Layer 2：项目初始化模板\n│       └── golang/                              # Go 项目模板\n│           ├── CLAUDE.md\n│           ├── .claude/\n│           │   ├── settings.json\n│           │   └── commands/\n│           └── docs/standards/build.md\n│\n└── specification-example/                       # 参考示例（学习用，非插件读取）\n    ├── team/                                    # 团队层示例\n    ├── project/                                 # 项目层示例（含完整 Commands + Hooks 说明）\n    └── personal/                                # 个人层示例\n        └── CLAUDE.md\n```\n\n---\n\n## 插件工作机制\n\nClaude Code 插件会在以下时机自动将 `spec/` 中的规范注入到对话上下文：\n\n- **新项目初始化**：从 `spec/project-templates/\u003clang\u003e/` 复制模板到项目根目录\n- **对话开始时**：将 `spec/teams/CLAUDE.md` 及规范文档作为背景上下文加载\n- **项目层覆盖**：项目自身的 `CLAUDE.md` 和 `.claude/` 配置优先级高于团队层\n\n团队层规范的修改（PR 合并到本仓库）会自动被所有项目的下次对话使用，无需各项目手动同步。\n\n---\n\n## 团队共同维护的内容\n\n三层体系不是\"定义完就结束\"的文档，而是需要团队持续共建的活文档。以下是各类内容的维护责任和协作方式。\n\n### 规范文档（docs/standards/）\n\n团队所有成员都应参与规范的演进，而非只有技术负责人才能修改。\n\n| 文件                                                    | 说明                                   | 维护方式                     |\n| ------------------------------------------------------- | -------------------------------------- | ---------------------------- |\n| `spec/teams/docs/standards/architecture.md`             | 架构原则与 ADR 机制                    | 架构师主导，PR Review 决策   |\n| `spec/teams/docs/standards/coding/base.md`              | 通用编码规范（语言无关）               | 全员提 PR，技术负责人 Review |\n| `spec/teams/docs/standards/coding/go.md`                | Go 专项规范                            | Go 开发者维护                |\n| `spec/teams/docs/standards/coding/python.md`            | Python 专项规范                        | Python 开发者维护            |\n| `spec/teams/docs/standards/coding/typescript.md`        | TypeScript 专项规范                    | 前端/TS 开发者维护           |\n| `spec/teams/docs/standards/testing.md`                  | 测试策略与规范                         | 全员提 PR                    |\n| `spec/teams/docs/standards/security.md`                 | 安全开发规范                           | 安全负责人 + 全员提 PR       |\n| `spec/teams/docs/standards/docs-writing.md`             | 文档写作规范                           | 全员提 PR                    |\n| `spec/project-templates/\u003clang\u003e/docs/standards/build.md` | 构建规范模板，**项目初始化后必须填写** | 项目负责人负责，开发者补充   |\n\n\u003e **参考示例见 `specification-example/`，搜索 `[团队填写]` 找到所有待集体决策的空白。**\n\n### 自定义命令（.claude/commands/）\n\nCommands 是效率工具，鼓励全员贡献。好的个人命令应提升为项目或团队命令。\n\n| 层级   | 位置                                              | 维护者       | 当前内容                                       |\n| ------ | ------------------------------------------------- | ------------ | ---------------------------------------------- |\n| 团队层 | `spec/project-templates/\u003clang\u003e/.claude/commands/` | 技术负责人   | 新项目初始化时注入                             |\n| 项目层 | `\u003cproject\u003e/.claude/commands/`                     | 项目团队全员 | `/review` `/test` `/migrate`（示例，按需扩展） |\n| 个人层 | `~/.claude/commands/`                             | 个人自维护   | 不提交仓库，个人沉淀                           |\n\n**协作流程：**\n\n```\n个人在 ~/.claude/commands/ 验证新命令\n    ↓ 效果好，有通用价值\n提 PR 到项目 .claude/commands/\n    ↓ 多个项目都需要\n提 PR 到本仓库 spec/project-templates/\u003clang\u003e/.claude/commands/\n    ↓ 新项目初始化时自动包含\n```\n\n**扩展建议：** 以下场景适合沉淀为团队命令（欢迎贡献）：\n\n- `/debug`：系统性排查 bug（读日志 → 假设 → 验证）\n- `/release-note`：从 git log 生成发布说明\n- `/security-check`：针对 PR 的安全专项检查\n- `/onboard`：新成员项目快速上手引导\n- `/adr`：创建架构决策记录（ADR）\n\n### Hooks 配置（.claude/settings.json）\n\nHooks 是 Claude Code 的自动化防护层，应随项目成熟度逐步加强。\n\n| 层级               | 位置                              | 维护者     | 提交仓库                     |\n| ------------------ | --------------------------------- | ---------- | ---------------------------- |\n| 项目层（团队共享） | `\u003cproject\u003e/.claude/settings.json` | 项目负责人 | **是**（质量门禁对全员生效） |\n| 个人层（个人偏好） | `~/.claude/settings.json`         | 个人       | 否                           |\n\n**当前项目模板已包含的 Hooks（`project/.claude/settings.json`）：**\n\n| Hook           | 事件                       | 作用                                  |\n| -------------- | -------------------------- | ------------------------------------- |\n| 阻止 push main | `PreToolUse` (Bash)        | 防止 Claude 直接推送到保护分支        |\n| 自动 lint      | `PostToolUse` (Edit/Write) | 文件修改后自动检查，结果反馈给 Claude |\n| 完成通知       | `Stop`                     | 长任务完成后发送桌面通知              |\n\n**建议逐步补充的 Hooks：**\n\n- 阻止删除迁移文件（`PreToolUse`）\n- 修改测试文件后自动运行对应测试（`PostToolUse`）\n- 检测硬编码密钥（`PreToolUse`，可集成 gitleaks）\n- 关键操作写入审计日志（`PostToolUse`）\n\n---\n\n## 本地开发环境\n\n本仓库使用 [Prettier](https://prettier.io/) 对 Markdown 等文件进行格式检查（通过 PostToolUse Hook 自动触发）。\n\n**安装依赖：**\n\n```bash\nnpm install\n```\n\n\u003e 依赖已锁定在 `package.json`，执行后即可使用 `npx prettier` 进行格式化。\n\n---\n\n## 快速上手\n\n### 新成员 Day 1 操作（必做）\n\n**第一步：配置个人 Claude 设置**\n\n```bash\n# 参考个人层模板，配置你的工作风格偏好\ncp specification-example/personal/CLAUDE.md ~/.claude/CLAUDE.md\n# 打开编辑，填写个人偏好（回复语言、操作确认习惯等）\n```\n\n**第二步：了解当前项目的规范**\n\n进入任何项目后：\n\n- 读项目根目录的 `CLAUDE.md`——这是该项目的 Claude 规范入口\n- 读 `docs/standards/build.md`——本地开发环境启动方式、常用命令\n- 在 Claude Code 中输入 `/` 查看项目提供的自定义命令列表\n\n**第三步：理解团队规范（按需）**\n\n团队级规范存放在本仓库 `spec/teams/docs/standards/`，涵盖：\n\n- 编码规范（通用 + 各语言专项）\n- 测试策略\n- 安全开发要求\n- 文档写作规范\n\n插件会自动将这些规范注入 Claude 上下文，通常无需手动阅读全部，但遇到规范相关问题时可直接查阅。\n\n---\n\n### 新项目初始化\n\n**方式一：使用插件（推荐）**\n\n插件会自动从 `spec/project-templates/\u003clang\u003e/` 复制模板到新项目，包含：\n\n- 项目根目录 `CLAUDE.md`（含团队规范引用）\n- `.claude/settings.json`（Hooks：防护 + 自动 lint + 完成通知）\n- `.claude/commands/`（`/review` `/test` `/migrate` 等基础命令）\n- `docs/standards/build.md`（待填写的构建规范模板）\n\n**方式二：手动复制**\n\n```bash\n# 以 Go 项目为例\ncp -r spec/project-templates/golang/. \u003cyour-project\u003e/\n\n# 然后填写项目信息\n# 1. 编辑 CLAUDE.md，替换所有 [填写] 占位符\n# 2. 填写 docs/standards/build.md（本地启动方式、必填环境变量等）\n```\n\n**初始化后必做：**\n\n```bash\n# 找到所有待填写的占位符\ngrep -r \"\\[填写\\]\" \u003cyour-project\u003e/\n```\n\n---\n\n### 贡献新规范或命令\n\n```bash\n# 1. 在项目 .claude/commands/ 下新建并验证\nvim .claude/commands/\u003ccommand-name\u003e.md\n\n# 2. 在 Claude Code 中立即可用（输入 / 查看命令列表）\n\n# 3. 效果好、有通用价值 → 提 PR 到本仓库\ngit add spec/project-templates/\u003clang\u003e/.claude/commands/\u003ccommand-name\u003e.md\ngit commit -m \"feat: add /\u003ccommand-name\u003e command for \u003c用途\u003e\"\n```\n\n---\n\n## 各层职责边界\n\n| 层级   | 位置                  | 管理者              | 规范文档               | Commands       | Hooks              |\n| ------ | --------------------- | ------------------- | ---------------------- | -------------- | ------------------ |\n| 团队层 | 本仓库 `spec/teams/`  | 技术负责人 / 架构师 | 跨项目通用原则         | 通用工作流命令 | 不适用             |\n| 项目层 | 各项目仓库 `.claude/` | 项目负责人 + 全员   | 项目特有约定、构建规则 | 项目特有命令   | 质量门禁、安全防护 |\n| 个人层 | `~/.claude/`          | 个人开发者          | 工作风格、个人偏好     | 个人探索命令   | 个人习惯自动化     |\n\n**模板来源：** 项目层的初始文件来自本仓库 `spec/project-templates/\u003clang\u003e/`，由插件注入或手动复制后在各项目仓库独立维护。\n\n---\n\n## 文件命名约定\n\n| 规范类型   | 文件名                            | 层级         |\n| ---------- | --------------------------------- | ------------ |\n| 架构规范   | `docs/standards/architecture.md`  | 团队 / 项目  |\n| 编码基础   | `docs/standards/coding/base.md`   | 团队         |\n| 语言规范   | `docs/standards/coding/\u003clang\u003e.md` | 团队         |\n| 测试规范   | `docs/standards/testing.md`       | 团队         |\n| 安全规范   | `docs/standards/security.md`      | 团队         |\n| 文档规范   | `docs/standards/docs-writing.md`  | 团队         |\n| 构建规范   | `docs/standards/build.md`         | 项目（必填） |\n| 自定义命令 | `.claude/commands/\u003cname\u003e.md`      | 项目 / 个人  |\n| Hooks 配置 | `.claude/settings.json`           | 项目 / 个人  |\n\n---\n\n## 演进流程\n\n所有内容（规范、命令、Hooks）遵循同一条演进路径：\n\n```\n个人发现痛点或好的实践\n    ↓\n在个人层验证（~/.claude/commands/ 或本地实验）\n    ↓\n效果好 → 提 PR 到所在项目层（各项目仓库）\n    ↓\n经项目负责人 Review 合并\n    ↓\n发现跨项目通用价值 → 提 PR 到本仓库 spec/\n    ↓\n技术负责人审批 → 合并 → 插件自动为新项目注入\n```\n\n---\n\n## 如何维护本仓库\n\n### 修改团队级规范\n\n编辑 `spec/teams/docs/standards/` 下对应文件，提 PR，技术负责人 Review 后合并。\n合并后插件会在下次对话中自动使用新规范，**无需通知各项目**。\n\n### 新增/修改项目模板\n\n编辑 `spec/project-templates/\u003clang\u003e/` 下文件，提 PR。\n已存在项目不受影响（模板只在初始化时使用），新项目会自动使用最新模板。\n\n### 新增语言模板\n\n```bash\n# 以 Python 为例\ncp -r spec/project-templates/golang spec/project-templates/python\n# 修改其中的语言相关内容（CLAUDE.md、build.md、commands）\ngit add spec/project-templates/python\ngit commit -m \"feat: add python project template\"\n```\n\n### 需要集体决策的位置\n\n```bash\n# 搜索所有待团队填写的空白\ngrep -r \"\\[团队填写\\]\" spec/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensourceways%2Fagent-development-specification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopensourceways%2Fagent-development-specification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensourceways%2Fagent-development-specification/lists"}