prose 是一套写作风格指南,用于指导代码注释、提交信息、拉取请求、README 和文档等书面表达。它要求语言简单、使用平实英语,能用普通词就不用术语,避免缩写(如用 durable object 而非 DO,AI、API 等约定俗成缩写除外),始终使用美式英语,不在代码中插入标记注释,也不在正文中使用装饰性字符。写作时不要提及对话、聊天记录、评审线程、智能体或开发会话,产出应能独立成立。
语气上要求像工程师对工程师说话,避免企业或创业腔调;不假设读者具备专业背景;诚实、清晰,必要时可以幽默但不排他;多用主动语态,直接称呼读者“你”,不要滥用感叹号。用词上偏好简单动词,如 improve 而非 revolutionize、use 而非 leverage、help 而非 assist、let 而非 enable、make sure 而非 ensure;多用动词少用名词;删去无信息量的副词;避免 easy、simply、just 等词,也避免 crazy、lame 等排他性用语。
格式上标题用句子大小写,层级保持扁平;文件名、命令、类名、函数名和标识符用代码格式;读者要运行的命令和超过一行的示例用代码块;日期用 ISO 8601(2024-10-24)或人类可读格式,不用 10/24/2024;不要滥用加粗;邮箱地址直接写出而非藏在 mailto: 链接后;默认使用 GitHub 风格 Markdown,段落内不硬换行。
提交信息部分给出结构:主题行、空行、可选正文。主题行用祈使语气,摘要部分首字母大写,不加句号,目标不超过 50 字符,硬上限 72;作用域前缀按项目约定保留小写。正文每行 72 字符换行,解释改了什么和为什么,而非怎么做。禁止对话式短语、第一人称复数(指开发对话时)、外部引用(其他提交 SHA、计划文件、评审线程、聊天记录、任务编号等),允许 (#N) 形式的拉取请求尾注。正文不用标题和项目符号列表,优先散文段落;陈述事实而非论证;保持自包含;保留 Signed-off-by:、Co-authored-by:、Reviewed-by:、Fixes: 等尾注原样。资料还给出提交信息改写前后的示例,并指出拉取请求正文可参考单独的 pull-requests 技能。