huang
6fc90abeb6
主要变更: 1. 新增 cmd/api/docs.go 实现文档自动生成逻辑 2. 修改 cmd/api/main.go 在服务启动时调用文档生成 3. 重构 cmd/gendocs/main.go 提取生成函数 4. 更新 .gitignore 忽略自动生成的 openapi.yaml 5. 新增 Makefile 支持 make docs 命令 6. OpenSpec 框架更新和变更归档 功能特性: - 服务启动时自动生成 OpenAPI 文档到项目根目录 - 保留独立的文档生成工具 (make docs) - 生成失败时记录错误但不影响服务启动 - 所有代码已通过 openspec validate --strict 验证 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
29 lines
2.5 KiB
Markdown
29 lines
2.5 KiB
Markdown
---
|
|
name: OpenSpec: Proposal
|
|
description: Scaffold a new OpenSpec change and validate strictly.
|
|
category: OpenSpec
|
|
tags: [openspec, change]
|
|
---
|
|
<!-- OPENSPEC:START -->
|
|
**Guardrails**
|
|
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
|
|
- Keep changes tightly scoped to the requested outcome.
|
|
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
|
|
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
|
|
- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
|
|
|
|
**Steps**
|
|
1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
|
|
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
|
|
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
|
|
4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
|
|
5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
|
|
6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
|
|
7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
|
|
|
|
**Reference**
|
|
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
|
|
- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
|
|
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
|
|
<!-- OPENSPEC:END -->
|