一键导入
bep-guide
Guide for writing and managing BEPs (Backend.AI Enhancement Proposals) - creation workflow, document segmentation, context-for-ai blocks, Decision Log
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
菜单
Guide for writing and managing BEPs (Backend.AI Enhancement Proposals) - creation workflow, document segmentation, context-for-ai blocks, Decision Log
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Guide for implementing REST and GraphQL APIs (create, get, search, update, delete, purge, scope prefix patterns, admin_ prefix, SearchScope, BaseFilterAdapter, @api_function, Click CLI)
./bai v2 CLI usage for testing/verifying API endpoints and managing resources — entity-command reference, login/config, search patterns, testing workflow (REST API client, NOT the v1 backend.ai CLI)
Guide for implementing Backend.AI client SDK and CLI (Session, BaseFunction, @api_function, Click commands, Pydantic models, FieldSpec, output handlers, APIConfig, testing)
Trace a feature across the layered architecture (REST v2, GraphQL, Service, Repository, DB, Errors) and explore the entity source tree — includes how to read the 21k-line supergraph.graphql without loading it whole
Inspect and apply database schema migrations (alembic current/heads, upgrade, downgrade, diverged heads) for Backend.AI components (manager, accountmgr, appproxy)
Local server management — ./dev start/stop/restart via tmux, startup-crash debugging, pre-flight infra checks, raw component start-server commands, post-change restart workflow
| name | bep-guide |
| description | Guide for writing and managing BEPs (Backend.AI Enhancement Proposals) - creation workflow, document segmentation, context-for-ai blocks, Decision Log |
| version | 1.1.0 |
| tags | ["bep","proposal","documentation","design"] |
Guide for creating and managing Backend.AI Enhancement Proposals (BEPs).
This skill is the process guide — how to structure, write, and manage BEPs.
The template (proposals/BEP-0000-template.md) is the blank document to copy and fill in.
1. Reserve Number → 2. Create JIRA → 3. Create Branch → 4. Write BEP → 5. Submit PR → 6. Discussion → 7. Accept/Reject
Edit proposals/README.md — add entry to the BEP Number Registry table:
| 1046 | Your Proposal Title | Your Name | Draft |
Numbers start from 1000. Pick the next available number.
Create a JIRA issue for the BEP and link it in the Related Issues section.
Short BEP (estimated < 500 lines): Single file.
cp proposals/BEP-0000-template.md proposals/BEP-XXXX-title.md
Long BEP (estimated >= 500 lines): Use segmented structure. See Document Segmentation.
---
Author: Full Name (email@example.com)
Status: Draft
Created: YYYY-MM-DD
Created-Version: YY.Sprint.Patch
Target-Version:
Implemented-Version:
---
A BEP is a readable tech spec, not an implementation log — describe interfaces, contracts, and decisions; leave concrete code, SQL, and file-by-file steps to the PR (see "Writing style" in the root AGENTS.md).
Each section has a specific purpose. Write in this order:
| Section | Purpose | Length | Avoid |
|---|---|---|---|
| Related Issues | JIRA/GitHub links | 2-5 lines | — |
| Motivation | Why this change is needed | 10-30 lines | how to implement it |
| Current Design | What exists today | 10-50 lines | full source dumps |
| Proposed Design | The new design | Main body, be specific | step-by-step code, class-by-class listings |
| Migration / Compatibility | Breaking changes, migration plan | 10-30 lines | full SQL/script bodies |
| Implementation Plan | Phased steps | 10-30 lines | line-by-line tasks, code |
| Decision Log | Key decisions with rationale | append | re-arguing settled decisions |
| Open Questions | Unresolved items | update | — |
| References | Related docs, BEPs | 2-10 lines | — |
Decision Log / Open Questions lifecycle:
bep/XXXX-short-titleSegment a BEP when any of these apply:
proposals/
├── BEP-XXXX-title.md # Main: overview + motivation + index (< 200 lines)
└── BEP-XXXX/ # Directory uses BEP number only
├── component-a.md # Component A detailed design
├── component-b.md # Component B detailed design
├── migration.md # Migration plan (if complex)
└── diagrams/ # Images, schemas
Main document serves as overview. Directory name uses BEP number only (e.g., BEP-1046/).
Use descriptive file names without number prefixes.
Separate overview.md file is optional for very large BEPs (5+ sub-documents).
The main file must be concise (under ~200 lines) — overview + index only. Beyond the standard sections (Step 5), segmented-main adds a context-for-ai master block and a Document Index:
<!-- context-for-ai
type: master-bep
scope: One-line summary
detail-docs: [component-a.md, component-b.md, migration.md]
key-constraints: [constraint 1, constraint 2]
key-decisions: [decision 1 (from Decision Log)]
phases: 3
-->
# Title
## Document Index
| Document | Description |
|----------|-------------|
| [component-a](./BEP-XXXX/component-a.md) | Data model and queries |
| [component-b](./BEP-XXXX/component-b.md) | API design and handlers |
## Decision Log
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-01-15 | Event-driven over polling | Lower latency |
(+ standard sections — Motivation, Implementation Plan, Open Questions, References — per Step 5)
Each sub-document is self-contained and focused on one work unit:
<!-- context-for-ai
type: detail-doc
parent: BEP-XXXX (Title)
scope: one-line scope description
depends-on: [other-component.md]
key-decisions:
- reference relevant Decision Log entries in main doc
-->
# BEP-XXXX: Component Name
## Summary
(1-3 sentences: what this component does)
## Current Design
(What exists today for this component)
## Proposed Design
(Detailed design for this component)
## Interface / API
(Public interfaces, data models, function signatures)
## Implementation Notes
(Constraints, dependencies on other components)
data-model.md, config-schema.md, event-registration.mdAdd <!-- context-for-ai --> to main document and each sub-document. This block is read by AI agents to quickly understand scope and constraints without parsing the entire document. Use key-value format for consistent parsing.
Main document (type: master-bep):
| Key | Purpose |
|---|---|
scope | One-line summary of the proposal |
detail-docs | List of sub-document file names |
key-constraints | Non-goals and hard constraints |
key-decisions | Critical decisions from Decision Log |
phases | Number of implementation phases |
Sub-document (type: detail-doc):
| Key | Purpose |
|---|---|
parent | Parent BEP number and title |
scope | What this document covers |
depends-on | Other sub-documents this depends on |
key-decisions | Relevant Decision Log entries from main doc |
See proposals/README.md for the full status lifecycle, transition rules, and version fields.
These patterns apply when an AI agent (e.g., Claude) works with BEPs. They also serve as guidelines for humans assigning BEP-related tasks to AI agents.
proposals/README.md registry for related proposals<!-- context-for-ai --> block to every documentWhen assigned work based on a BEP:
Example task prompt:
Implement Phase 1 of BEP-1046. Follow the Decision Log in the main document. Refer to config-schema.md and event-registration.md for details.
proposals/README.md — BEP process, number registry, file structure rulesproposals/BEP-0000-template.md — Blank template to copy (sections with example content)/test-guide — Test scenarios for implementation phase