publication-ready-docs-jev
Skill9 starsChanged 3 days agoMITView on GitHub
撰写、精简和审查正式工程文档,用 Jev 检测冗余表达与跨章节重复。适用于发布前检查、冗余清理和质量复核。
- Reads credentials
In this repository17 other files it gives its agents.
- brief-outputSkill
- google-go-styleSkill
- insight-collectorSkill
- insights-reportSkill
- json-canvasSkill
- md2wechatSkill
- note-creatorSkill
- obsidian-basesSkill
- obsidian-markdownSkill
- peleSkill
- portpilot-assistantSkill
- publication-ready-docsSkill
- readme-maintainerSkill
- sync-to-githubSkill
- tech-articleSkill
- wechat2mdSkill
- wechat-archiverSkill
The file
Files
Publication Ready Docs with Jev
工程文档让读者能独立理解、实施、运行和验证。先查证事实,再确定本次必要内容,先删后改,用 Jev 预审冗余,最后人工核对语义。
内容范围
- 详细设计 / 技术方案:目标、规则、改动对象、职责、接口契约、状态流转、关键代码和配置。
- 运行手册:前置条件、操作步骤、回滚和恢复。
- 测试与审计:验证场景、预期结果、实测结果;审计、复盘和 ADR 保留必要权衡。
按文档类型和任务取舍章节,按真实主题合并零碎小节,标题层级统一。部署、测试或审查证据按需写入。
工作流程
- 查证来源:核对源码、规范、表结构、配置与既有详设。简述复用机制与本次差异。需要定位时标注模块、文件、类、函数或配置项。
- 确定内容:列出读者需要的事实、规则、改动对象、关键代码和配置。先用可用工具查源码、规范、配置和已有查询结果;需要用户协助时,在会话给出具体查询项或 SQL,取得结果后写入正文。影响方案成立的外部业务条件保留,并在会话确认。
- 区分状态:分别写清现有行为、拟设计方案和已实施结果。
- 先删再润色:删除后读者仍能完成任务的内容直接删去。保留内容简写为规则和条件。清理过程记录、自我评价、空泛承诺、重复定义、模板空章节和无新增信息的提醒。
- 去重:一个事实只定义一次。字段位数、枚举和约束写在表格时,正文只写表格未覆盖的类型和解析规则。同步检查正文、表格单元格、括注和代码注释。仅清理文字和注释时,代码执行语句保持原样;方案调整时,同步修改代码和契约。
- Jev 预审:草稿完成后运行自动审查,报告作为线索决定删、改、留。仅审查时交付报告;获得授权后,基于最新版本局部修改正文、表格、代码和前提条件,改后回读。
- 核对并同步:核对语义、边界、职责、数值和未决条件,沿用项目约定的模板,保留既有图表资源。交付前按参考复核。
Jev 自动审查
python3 scripts/jev_doc_review.py <input.md> --doc-type 详细设计脚本扫描正文、表格单元和已知语言的代码注释;代码执行语句只作上下文。输出 <input>.review.md 和 <input>.review.json,默认不改原文。运行需要 TYPESAFE_API_KEY、Python 3.10+ 和 typesafe_sdk。未闭合代码块和无法识别的语言记入 skipped。
报告是线索,按信息价值和项目必要性决定删、改、留:
- 建议删除、合并或改写:结合上下文核对,同一事实保留权威定义。
- 表格单元:按表头和同行字段理解。完整字段表定义(含各单元格)优先于正文和注释复述;同一行不同列不是重复定义。
- 代码注释:按相邻代码理解。复述正文或表格的注释删除,独立说明保留。
- 调用失败:记录失败,继续人工审查,并说明自动审查未完成。
写作规则
- 短句、主动语态、一句一个要点。术语首次出现时定义,全篇用同一叫法。条件写在动作前。命令、路径、表名和字段名用代码格式。
- 规则写清主体、条件、动作和结果。必要边界用正面具体指令表达,例如“只更新
A表的B字段”。 - 字段禁填、长度、枚举含义、事务边界、失败后果、兼容性和数据写入范围保留一次。
- 引用外部规范时保留其条件、建议强度和例外。规范已有定义时直接引用或链接。项目补充只写已确认的差异和新增约定。其余比较、提醒和复述删去。
- 直接陈述规则和条件,删除包装语、防御性对照和过强语气。
详细设计检查项
- 源码位置写完整
文件:行号。同一文件再次引用时才可省略文件名。 - 分开写现有行为、本次改动、不改动对象。已确认的结论写进正文,从待确认移除。
- 效果和取数写具体名称与取值,例如“活跃门店数”“默认
0.95”。不用比喻替代指标,不写没有测量依据的性能结论。 - 不用自造词和非常用缩写。沿用工程和业务里已有的叫法,例如“判定条件”不写“判定式”;必须自造时在首次出现处定义。
- 代码改动按文件分节:位置、关键代码、触发条件、未改动部分。代码已表达的步骤不再用文字复述。
- 测试用例写具体输入值和预期结果,不用“任意”“不涉及”占位。
- 沿用项目模板的章节名和编号。模板中无内容的章节整节删除。
参考
- 常见坏味道:成稿后逐项复核。
- 转换示例:处理目录说明、包装语、来源提醒、配置值、重复定义或事务边界时对照。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

