writing-discipline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Discipline

写作规范

文章生成を、agentが保持しているconversation / task / investigation / execution contextのserializationとして扱わない。

agentは作業中に大量のtext contextを保持する。そこに存在する情報を、その順序や粒度のまま成果物へ転写すると、会話・調査・作業の足場が文章へ混入する。persistentまたは他者向けのtextは、raw contextを縮約するのではなく、readerへ伝える内容を選び直し、独立したartifactとして再構成する。

原則:

Think in context. Select for purpose. Compose for the reader. Reread without the context.

不要将文章生成视为对 Agent 所持有的 conversation / task / investigation / execution context 的序列化。

Agent 在工作过程中会保留大量文本上下文。如果按照这些信息原有的顺序和粒度直接转写到成果中，conversation、investigation 和工作过程的脚手架就会混入文章。持久化文本或面向他人的文本并不是对原始上下文的简单缩略，而是要重新选择需要向读者传达的内容，并将其重构为一个独立的 artifact。

原则：

在上下文中思考。为目的而选择。为读者而组织。脱离原有上下文重读。

1. Scope

1. 适用范围

このSkillは、少なくとも次のtextを新規作成・更新するときに適用する。

README / development guide / architecture docs / reference docs
ADR / design / specification
GitHub Issue / Pull Request description
commit message
code comment / doc comment
review comment
release note / migration note
repository-controlled agent instructions / Skills

private scratchpadや一時的な内部整理を、ここでいうreader-facing artifactとして扱わない。ただし、内部整理をそのままpersistent artifactへ昇格してはいけない。

这个 Skill 至少适用于新建或更新以下文本：

README / 开发指南 / 架构文档 / 参考文档
ADR / 设计 / 规范
GitHub Issue / Pull Request description
commit message
code comment / doc comment
review comment
release note / migration note
由仓库管理的 Agent 指令 / Skills

不要将 private scratchpad 或临时性的内部整理视为这里所说的面向读者的 artifact。不过，也不能将内部整理原封不动地提升为持久化 artifact。

2. Writing is not context serialization

2. 写作不是上下文序列化

文章へ含める理由を「current contextに存在するから」にしてはいけない。

特に次を、そのまま文章化しない。

conversationの流れ
userとのやり取りの順序
agentが調査した順序
trial-and-errorの履歴
作業中に見つけた中間状態
branch / commit / CI / tool outputの現在値
他agentから受け取ったraw report
internal planning labelやscratch structure
「今回」「先ほど」「現在」等、artifact外のcontextへ依存するreferent

これらがartifactの意味、readerの判断、reproducibility、auditabilityに本当に必要なら含めてよい。時間性や履歴性そのものを禁止するのではなく、readerへ伝える必要性を根拠にする。

判断基準:

その情報は、agentが知っているから書くのか。それとも、このartifactのreaderが知る必要があるから書くのか。

前者なら原則として捨てる。

不要以“信息存在于当前上下文中”为理由，将其写入文章。

尤其不要原样写入以下内容：

conversation 的推进脉络
与用户交互的顺序
Agent 的调查顺序
trial-and-error 的历史
工作过程中发现的中间状态
branch / commit / CI / tool output 的当前值
从其他 Agent 收到的 raw report
internal planning label 或 scratch structure
依赖 artifact 外部上下文的指代，例如“这次”“刚才”“目前”

如果这些内容对于 artifact 的含义、读者的判断、reproducibility 或 auditability 确实必要，可以包含。这里并非禁止时间性和历史性本身；是否保留，必须以“读者是否有必要知道”为依据。

判断标准：

写这条信息，是因为 Agent 知道它，还是因为这个 artifact 的读者需要知道它？

如果是前者，原则上应当舍弃。

3. Required writing pipeline

3. 必需写作流程

raw contextから直接final proseを作らない。

不要直接从原始上下文生成最终文章。

Phase A: Select

Phase A：选择

書く前に次を決める。

audienceは誰か
artifactの目的は何か
readerが判断・理解・行動するために必要なfact / decision / constraint / rationaleは何か
readerに不要なconversation / execution / investigation scaffoldingは何か
理解順に並べると、どの構造が自然か

ここでは文章を書き始めるより先に、communicative contentを確定する。

raw contextの順序を維持する必要はない。調査順、実装順、会話順ではなく、readerが理解する順序を選ぶ。

在开始写之前，先确定：

受众是谁
artifact 的目的是什么
读者为了作出判断、理解或采取行动，需要哪些事实、决策、约束和理由
哪些 conversation / execution / investigation scaffolding 是读者不需要的
按照理解顺序排列时，哪种结构最自然

在这一步，应先确定要传达的内容，而不是开始写文章。

无需保持原始上下文的顺序。不要按照调查顺序、实现顺序或 conversation 顺序排列，而要选择读者最容易理解的结构。

Phase B: Compose

Phase B：组织

Selectしたcommunicative contentだけからstandalone proseを組み立てる。

artifact単体で意味が通るようにする
主語・対象・referentをartifact内で解決する
必要な因果や接続を明示する
readerに不要な作業者視点を消す
raw noteの箇条書きを、そのまま完成文章とみなさない
同じ事実を複数の表現で反復しない
internal taxonomyやagent都合のsection構造を、reader都合の構造へ変換する
rationaleを書く場合はdecision理解に必要な範囲へ限定する
chronological narrativeが不要なら、conceptual structureへ組み替える

仅使用选定的传达内容，组织成一篇独立的文章。

使其作为独立 artifact 时也能表达完整含义
在 artifact 内明确主语、对象和指代
明确必要的因果关系和连接
删除读者不需要的执行者视角
不把原始笔记的项目符号列表直接当作完成稿
不以不同表达重复同一个事实
将 internal taxonomy 或方便 Agent 使用的章节结构，转换为方便读者理解的章节结构
如果需要解释理由，只写到足以理解决策的范围
如果不需要按时间顺序叙述，则重组为概念结构

Phase C: Reread

Phase C：重读

draftを完成扱いする前に、元contextを知らないreaderとして全文を読み直す。

Do not validate the prose against memory of the task. Read it as a standalone artifact.

確認する:

前のconversationや作業経緯を知らなくても意味が通るか
書き手には自明だがreaderには欠けている前提がないか
指示語や「今回」「現在」等がartifact外へ依存していないか
文と文、段落と段落の接続が自然か
調査順・思考順ではなく理解順になっているか
同内容の重複や言い換え反復がないか
箇条書きがcontext dumpになっていないか
不要なstatus / history / implementation diaryが混ざっていないか
internal reasoning labelやtool terminologyが露出していないか
一文ごとは正しくても、段落全体として不自然になっていないか
readerが必要としない説明をしていないか
逆に、readerが必要とする理由・制約・前提が抜けていないか

問題があれば、追記だけで直そうとせず、順序変更・統合・削除・書き直しを行う。

将 draft 视为完成稿之前，以不了解原始上下文的读者身份通读全文。

不要依据对任务的记忆来验证文章。要把它当作一个独立的 artifact 来阅读。

检查：

不了解前面的 conversation 或工作经过时，是否仍能理解？
是否有作者认为显而易见、但读者缺少的前提？
指代词、“这次”“目前”等是否依赖 artifact 外部上下文？
句子之间、段落之间的连接是否自然？
是否按照理解顺序，而不是调查顺序或思考顺序组织？
是否重复表达相同内容？
项目符号列表是否只是堆砌上下文？
是否混入不必要的状态、历史或实现日志？
是否暴露了内部推理标签或工具术语？
是否存在每句话都正确，但整段读起来不自然的情况？
是否包含了读者不需要的解释？
反过来，读者需要的理由、约束或前提是否有所缺失？

如果发现问题，不要只靠追加内容来修正，而应重新排序、合并、删除或改写。

4. Artifact-specific guidance

4. 不同 artifact 的写作指导

Documentation

利用者が理解・操作・保守するためのcanonical knowledgeを書く。

authorの作業履歴ではなく、対象のbehavior / contract / procedureを書く
version-sensitive informationは必要ならversion/sourceを明示する
obsoleteなmigration historyをcurrent procedureへ混ぜない
troubleshootingでは再現可能なsymptom / cause / diagnosis / remedyを中心にする

编写 canonical knowledge，使用户能够理解、操作和维护目标。

写目标对象的行为、契约和流程，而不是作者的工作履历
对版本敏感的信息，必要时明确版本和来源
不要把过时的迁移历史混入当前流程
故障排查应以可复现的症状、原因、诊断和修复方法为核心

ADR

decisionを理解・再評価するために必要なproblem structure、constraints、decision、consequencesを書く。

meeting/chat transcriptにしない
調査ログにしない
「この作業でこうなった」ではなく、なぜこのdecisionが妥当かを書く
chronologyがdecision理解に必要な場合だけhistoryを残す

写清理解与重新评估决策所需的问题结构、约束、决策和后果。

不要写成会议或聊天记录
不要写成调查日志
不要写“因为这项工作最后变成了这样”，而要说明为什么该决策合理
仅在理解决策确实需要时保留历史

Issue

解くべきproblem、desired outcome、constraints、acceptance criteria、dependencyを書く。

発見までの会話を再現しない
implementation diaryを先回りして書かない
unresolved consequential decisionがある場合だけ明示する

写清待解决的问题、预期结果、约束、验收标准和依赖关系。

不要复现问题发现之前的 conversation
不要提前写入实现日志
仅当存在重大且尚未解决的决策时才明确说明

Pull Request

reviewerがchangeの意図・surface・重要なdesign decision・validationを評価するために必要な内容を書く。

commit historyの散文要約にしない
branch同期やtrial-and-errorの経緯を通常本文へ書かない
current SHA / ahead-behind / bot status等を、reader判断に必要でない限り本文へ転写しない
「何を変えたか」だけでなく、non-obviousな「なぜ」を必要な範囲で書く

写清 reviewer 评估 change 的意图、影响范围、重要设计决策和 validation 所需的信息。

不要将 commit history 改写成散文摘要
通常不要在正文中记录 branch 同步或 trial-and-error 的过程
除非读者作出判断确实需要，否则不要将 current SHA / ahead-behind / bot status 等信息写入正文
不仅要说明“改了什么”，还要在必要范围内解释不明显的“为什么”

Commit message

commitによるrepository stateの意味ある変化を書く。

agentが何を試したかではなく、commitが何を変えるかを書く
temporary failureやtool invocationを記録しない
rationaleが重要ならbodyで簡潔に補う

写清 commit 对 repository state 造成的有意义变化。

不要写 Agent 尝试过什么，而要写 commit 改变了什么
不要记录临时失败或 tool invocation
如果理由很重要，可在正文中简要补充

Code comment / doc comment

codeから自明でないintent / invariant / constraint / contractを書く。

変更履歴を書かない
「ここを修正した」「以前は〜だった」を通常commentとして残さない
codeの逐語的説明を繰り返さない
work contextではなく、future maintainerが必要とする意味を書く

写 code 中无法直接看出的 intent / invariant / constraint / contract。

不要记录变更历史
通常不要在 comment 中留下“这里修好了”“以前是……”之类的内容
不要逐字复述 code
写未来维护者需要的含义，而不是工作上下文

Review comment

recipientが問題を理解し、判断または修正できる形へ整える。

「見ていて気になった」等のreviewer実況を不要に含めない
問題箇所、影響、根拠、期待する状態を明確にする
raw thought processや調査過程を貼り付けない

将内容整理成接收者能够理解问题并作出判断或修正的形式。

不要包含“看着觉得有点奇怪”等 reviewer 实况
明确问题位置、影响、依据和期望状态
不要粘贴原始思考过程或调查过程

5. Temporal and execution information

5. 时间信息与执行信息

temporal informationを禁止しない。

次のいずれかを満たす場合は残してよい。

version compatibilityを正しく説明する
migration / deprecation / rolloutを理解するために必要
incident / audit / security recordとして必要
reproducibilityに必要
readerが現在の判断を誤るのを防ぐ
artifact自体がstatus report / changelog / runbook recordである

それ以外のcurrent-state情報は、作業中に存在するという理由だけでpersistent proseへ昇格しない。

不禁止时间信息。

满足以下任一条件时可以保留：

正确说明版本兼容性
理解迁移、弃用或 rollout 所必需
作为 incident、audit 或 security record 必不可少
保证可复现性
避免读者对当前状态产生误解
artifact 本身就是 status report、changelog 或 runbook 记录

除此之外，不应仅因为当前状态信息在工作过程中存在，就将其提升为持久化文章。

6. Natural prose requires editing

6. 自然文章需要编辑

correctnessだけで文章品質を判定しない。

自然な文章には、少なくとも次の編集を行う。

redundant sentenceの削除
awkward transitionの書き直し
readerに合わせた情報順序への再配置
fragmented bulletsの統合
long sentenceの分割
repeated terminologyの整理
unnecessary meta-languageの削除
referentの明確化
paragraph単位でのtopic coherence確認

rereadはproofreadingだけではない。reader-oriented editingである。

不能只凭正确性判断文章质量。

自然的文章至少需要完成以下编辑：

删除冗余句
改写生硬的过渡
按照读者需要重新排列信息
合并零散的项目符号列表
拆分长句
整理重复术语
删除不必要的 meta-language
明确指代
检查段落层面的主题连贯性

重读不只是校对，而是面向读者的编辑。

7. Completion criterion

7. 完成标准

次を満たすまでreader-facing textを完成扱いしない。

audience / purposeが明確
communicative contentがraw contextから選別されている
conversation / execution scaffoldingが不要に残っていない
artifact単体で理解できる
artifact種別に適した情報だけが残っている
reread後に構造・接続・冗長・context dependenceを編集済み
temporal/history情報はreaderへの必要性で説明できる

文章量を増やすことを品質とみなさない。必要な情報を選び、自然に伝わる形へ整えることを品質とする。

在满足以下条件前，不要将面向读者的文本视为完成：

受众和目的明确
传达内容已从原始上下文中筛选出来
conversation / execution scaffolding 没有被无必要地保留下来
artifact 单独阅读时也能理解
只保留了适合当前 artifact 类型的信息
重读后已编辑结构、连接、冗余和上下文依赖问题
时间和历史信息的保留理由能够以读者必要性来解释

不要把增加篇幅视为质量。质量在于选择必要的信息，并将其整理为自然、易于传达的形式。