Urazuke — 课程第 2 部分：继承来的项目。把一个不是用方法诞生的系统规范化，然后让它演进

Before we touch anything, we are going to set the working agreement between you and me for a system that already exists and has users. Write docs/WORKING_AGREEMENT.md with the six rules of the method (my time is sacred; zero technical debt; exact scope; documentation in the same commit; never report as done what you have not verified; speak my language), each with one line explaining what it prevents, and these five rules for an inherited system: (7) Nothing is refactored that was not asked for, and no module is rewritten. (8) Code you do not understand is read before it is touched, and what you learn goes into the system map. (9) Anything strange you find (a secret in the code, a dead path, a duplicated rule, a query without an index) is logged as a pending item with its evidence, never fixed in passing. (10) Current behaviour is the specification until the owner says otherwise: a difference between what the code does and what the business says is a discrepancy for me to decide, not a bug for you to fix silently. (11) No change reaches the test environment without the characterization suite green. Add any rules you think this system needs, marked as proposals. If you need to know something about how I work in order to write this, ask me.

在我们动任何东西之前，要为一个已经存在、而且有用户的系统，定下你和我之间的协作契约。写 docs/WORKING_AGREEMENT.md，包含方法的六条规则（我的时间是神圣的；零技术债务；精确的范围；文档在同一次提交里；绝不把没验证过的东西报告为已完成；说我的语言），每条附一行说明它避免了什么，再加上这五条针对继承来的系统的规则：（8）不重构任何没被要求的东西，不重写任何模块。（11）你不理解的代码，先读再动，而你学到的东西要进系统地图。（7）你发现的任何怪事（代码里的一个密钥、一条死路径、一条重复的规则、一个没有索引的查询）都作为带证据的待办项记下来，绝不顺手修掉。（12）当前行为就是规格，直到所有者另有说法为止：代码做的事和业务说的事之间的差异，是一条由我来决定的不一致，不是一个由你悄悄修掉的 bug。（13）表征测试套件不绿，任何改动都不许进测试环境。你认为这个系统还需要什么规则，就加上，标为提案。如果你需要知道我是怎么工作的才能写出这份契约，就问我。

We are going to recover the map of this system from what exists. Read the whole repository (every branch), the database schema (read-only), the configuration of each environment, the recent logs and whatever documentation there is; if some part cannot be read from where you are, tell me and mark it as a gap; do not fill it by guessing. Then write three things. First, complete docs/INITIAL_SURVEY.md in the form the method expects (what the system does and for whom; what it does NOT do; who uses it; the technology; the environments; what an error costs), with every statement tagged by its source: [code], [database], [configuration], [documentation], [business] for what the survey already says, or [inferred]. Second, PROJECT.md, three hundred lines at most, and docs/SEMANTIC_TREE.md: the domains and, under each one, the actors, the processes (each with trigger, steps, outcome and exceptions as the code actually implements them), the entities with the attributes, states and transitions the database and the code enforce, the screens, the external integrations and the scheduled jobs; every node tagged the same way. Third, docs/DISCREPANCIES.md: everything where the code, the database, the documentation and what the business says in the survey do not agree, with the evidence on each side. Do not resolve any discrepancy and do not fix anything: list them. Create docs/STATUS.md for the living state. Reply in my language.

我们要从现有的东西里把这个系统的地图恢复出来。读整个仓库（所有分支）、数据库结构（只读）、每个环境的配置、最近的日志，以及现有的任何文档；如果某部分从你所在的位置读不到，告诉我并把它标为缺口；不要靠猜来填它。然后写三样东西。第一，按方法预期的形式补全 docs/INITIAL_SURVEY.md （系统做什么、给谁用；它不做什么；谁在用；技术；环境；一个错误的代价），每条断言都带上来源标记：[代码]、[数据库]、[配置]、[文档]、对调研里已经写了的东西用 [业务]，或者 [ 推断]。第二，PROJECT.md，最多三百行，以及 docs/SEMANTIC_TREE.md：各个领域，以及每个领域下面的参与者、流程（每个带触发条件、步骤、结果和异常，按代码实际实现的样子写）、实体连同数据库和代码真正强制的属性、状态和状态转移、界面、外部集成和定时任务；每个节点都用同样的方式打标记。第三，docs/DISCREPANCIES.md：代码、数据库、文档，以及业务在调研里说的话，这四者对不上的一切，附上各方的证据。不要解决任何一条不一致，也不要修任何东西：把它们列出来。创建 docs/STATUS.md 来记录活状态。用我的语言回复。

I confirm these nodes: [list]. Correct these: [list]. The discrepancies are decided as follows: [one line each: discrepancy, my decision, today's date]. Finalize docs/INITIAL_SURVEY.md, PROJECT.md and docs/SEMANTIC_TREE.md with today's date, keeping the source tags. Write each discrepancy decision in docs/DECISIONS.md with my exact words, and open a pending item in docs/PENDING.md for every discrepancy where I decided the system must change; for the ones where I decided the current behaviour stays, write it next to the node as a confirmed rule. Add to PROJECT.md the instruction to read this file, the tree and the working agreement at the start of every session.

我确认这些节点：[清单]。纠正这些：[清单]。那些不一致这样决定：[每条一行：不一致、我的决定、今天的日期]。用今天的日期关闭 docs/INITIAL_SURVEY.md、PROJECT.md 和 docs/SEMANTIC_TREE.md，保留来源标记。把每一条关于不一致的决定用我的原话写进 docs/DECISIONS.md，并且对每一条我决定要改系统的不一致，在 docs/PENDING.md 里开一条待办项；对那些我决定保留当前行为的，把它作为一条已确认的规则写在对应节点旁边。在 PROJECT.md 里加上一条指令：每次会话开始时读这个文件、语义树和协作契约。

Audit this system for integrity, security, performance, code quality and deployability, as the inventory of what must be normalized before and during its evolution. Read-only: change nothing except writing your report to docs/AUDIT_[date].md. If auditing some part requires access you lack (the database, the logs, the server), tell me and mark that part as not audited; do not pass it as fine. Go through all of the code, not a sample, and read docs/SEMANTIC_TREE.md and docs/DISCREPANCIES.md first so that you do not report what is already known. For every finding: where it is (file and line), the risk, the evidence that proves it (the command, the query, the number), its priority (P0 must be fixed now, P1 soon, P2 when possible), and one more field: whether it BLOCKS (must be fixed before any change, by my criteria: [an exposed secret, a screen that cannot be driven by a program, a deployment that cannot be repeated, no tested backup, anything that deletes or sends without control]), whether it is PAID WHEN TOUCHED (fixed together with the first change that enters its module), or whether it CAN WAIT. Grade every dimension you audited. End with every finding turned into a proposed pending item, blocking ones first. Reply in my language.

从完整性、安全、性能、代码质量和可部署性五个方面审计这个系统，作为"在演进之前和演进期间必须规范化什么"的清单。只读：除了把报告写到 docs/AUDIT_[日期].md，什么都不要改。如果审计某部分需要你没有的访问权（数据库、日志、服务器），告诉我并把那部分标为未审计；不要把它当成没问题。走遍全部代码，不是抽样，并且先读 docs/SEMANTIC_TREE.md 和 docs/DISCREPANCIES.md，免得报告已经知道的东西。对每条发现：它在哪里（文件和行）、风险、证明它的证据（命令、查询、数字）、它的优先级（P0 必须马上修，P1 尽快，P2 有条件时），再加一个字段：它是阻塞（任何改动之前必须修掉，按我的标准：[一个暴露的密钥、一个不能由程序操作的界面、一条不能重复的部署、没有验证过的备份、任何不受控制地删除或发送的东西]）、是触及时偿还（和进入它所在模块的第一个改动一起修掉），还是可以等待。给你审计过的每个维度打一个评级。最后把每条发现都变成一条提议的待办项，阻塞的排在前面。用我的语言回复。

We are going to build the safety belt around this system before changing anything in it. Read the environments survey, docs/AUDIT_[date].md and docs/SEMANTIC_TREE.md. Evaluate whether you have what is needed (read access to the server where it runs and to its database, write access to where the test environment will run, the way it is deployed today); if anything is missing, ask me before starting. Then set up, without touching any functionality: (1) a test environment that runs the system exactly as production does, with a copy of the data where the personal fields I listed are anonymized; (2) a reproducible deployment to that environment, run twice, showing me that the second run changed nothing; (3) every secret found in the repository or in the code moved to the server configuration (environment file or vault), with the list of what you moved so that I rotate each one; (4) continuous integration running whatever test suite exists today, even if it is a single smoke test, on every push; (5) docs/GATES.md with the gates of this project, including: nothing reaches the test environment without the characterization suite green, and nothing reaches production without the full suite green with the exact version. Document all of it in docs/DEPLOYMENT.md so that a person can do it by hand without you. Take a screenshot of the system running in the test environment and show it to me. Reply in my language.

在改动这个系统里的任何东西之前，我们要在它周围造一条安全带。读环境调研、docs/AUDIT_[日期 ].md 和 docs/SEMANTIC_TREE.md。评估你是不是具备所需的东西（对它运行所在的服务器和它的数据库的读访问权、对测试环境将要运行的位置的写访问权、它今天的部署方式）；如果缺什么，在开始之前向我索要。然后搭建以下东西，而且不碰任何功能：（1）一个测试环境，它运行这个系统的方式和生产完全一样，带一份数据副本，其中我列出来的那些个人字段已经匿名化；（2）一条到那个环境的可复现部署链，跑两遍，并演示给我看第二遍什么都没有改变；（3）仓库里或代码里找到的每一个密钥都挪到服务器配置里（环境文件或保险库），并给我一份你挪动过的清单，好让我把每一个都轮换掉；（4）持续集成，在每次 push 时运行今天现有的任何测试套件，哪怕只有一个冒烟测试；（5）docs/GATES.md，写上这个项目的闸门，包括：表征测试套件不绿，任何东西都不许到测试环境；完整测试套件不以确切版本变绿，任何东西都不许到生产。把这一切记录到 docs/DEPLOYMENT.md，让一个人不靠你也能手工完成。给我截一张系统在测试环境里运行的图并拿给我看。用我的语言回复。

We are going to write the characterization tests of these critical flows: [load an appointment; cancel an appointment; the reminder reaches the patient; search a patient; download the monthly sheet]. A characterization test captures what the system does today, exactly as it does it, defects included; it is not a test of what the system should do. For each flow: drive it from the screen as a user would and check the effect in the backend (the row, the state, the message queued). Every test must pass against the current code. Then prove that each test actually watches its flow: break the flow deliberately with a temporary change, show me the red output, revert the change, show me the green. If a flow cannot be driven from the screen, do not simulate it: say so and open a pending item marked as blocking. If while writing these tests you find behaviour that looks wrong, do not fix it: add it to docs/DISCREPANCIES.md with the evidence. Record the command to run the suite in docs/STATUS.md, and make the suite the gate for the test environment as docs/GATES.md says. Reply in my language.

我们要为这些关键流程写表征测试：[登记一个预约；取消一个预约；提醒送到患者那里；查找一个患者；下载月度表格]。一个表征测试捕捉的是系统今天做了什么、而且完全按它今天的做法，缺陷也照收不误；它不是一个检验系统"本该做什么"的测试。对每个流程：像用户那样从界面操作它，并在后端验证效果（那一行、那个状态、那条进了队列的消息）。所有测试都必须对着当前代码通过。然后证明每个测试真的在看守它那个流程：用一处临时改动故意把流程弄坏，给我看红色输出，再把改动撤回，给我看绿色。如果某个流程没法从界面操作，不要模拟它：说出来，并开一条标为阻塞的待办项。如果在写这些测试的过程中你发现某个行为看起来不对，不要修它：把它连同证据加到 docs/DISCREPANCIES.md 里。把运行测试套件的命令记录到 docs/STATUS.md，并按 docs/GATES.md 所说，让这套测试成为测试环境的闸门。用我的语言回复。

Go through the code, the database triggers and the scheduled jobs of the server looking for everything that charges, sends, approves, deletes, notifies outwards or runs on a schedule, and write docs/CONSEQUENTIAL_ACTIONS_SURVEY.md with every statement tagged by its source. Compare it with the list the business wrote in docs/INITIAL_SURVEY.md: whatever the code does that the business did not list, or the other way round, ask me about before going on. For every action: what triggers it, whether it can run twice, whether it is reversible, what lock exists today if any, and what the way back is. In the same pass, build docs/PRODUCER_CONSUMER_MAP.md: for every contract in the system (a service, a table, a file format, a list of values), who produces it and who consumes it, including the things outside the repository I told you about. If there are parts you cannot see, say so instead of leaving them out. Present me the actions table with a proposed lock for each (explicit confirmation, double safety, dry-run mode, daily limit, a human in the loop) and a proposal of which locks go NOW, before any change, and which can go when the module is touched. Do not implement anything yet: I confirm lock by lock. Reply in my language.

走遍代码、数据库触发器和服务器上的定时任务，找出一切会收钱、发送、批准、删除、对外通知或者按时间表自己运行的东西，并写 docs/CONSEQUENTIAL_ACTIONS_SURVEY.md，每条断言都带上来源标记。把它和业务写在 docs/INITIAL_SURVEY.md 里的那份清单做比对：代码做了而业务没列出来的，或者反过来，在继续之前都来问我。对每个动作：什么触发它、它会不会跑两次、它可不可逆、它今天有没有锁（如果有是什么锁），以及回头路是什么。在同一遍里，构建 docs/PRODUCER_CONSUMER_MAP.md：对系统里的每一份契约（一个服务、一张表、一种文件格式、一份取值清单），谁生产它、谁消费它，包括我告诉过你的那些仓库之外的东西。如果有些部分你看不到，说出来，不要把它们略掉。把动作表呈给我，每个动作附一把提议的锁（显式确认、双重保险、演练模式、每日上限、回路中的人），以及一份提案：哪些锁现在就上，在任何改动之前，哪些可以等到触及那个模块时再上。先不要实现任何东西：我一把锁一把锁地确认。用我的语言回复。

Before changing anything we are going to size this system with its real numbers. With read-only access to the production database (or the complete test copy) and to the logs, measure instead of asking: rows per table and growth per month from the timestamps, events per entity, peak concurrency from the access logs, data size today and projected at five years, and the slowest queries. Write a meter for each number (a script that lives in the repository, with a test against a known case I will give you) and show me every number together with the command that produces it; audit each meter in both directions (is everything that should be counted, counted? does everything counted exist?). Write docs/VOLUME_SURVEY.md with every figure tagged [database] or [log], and ask me only for what cannot be measured: the growth the business expects and whether the system will serve more than one site. Then write docs/SIZING.md: what breaks first if everything is multiplied by ten, which of the current architecture choices hold and which do not, and which asymmetric decisions we take now, before evolving, because they are cheap today and expensive later. Do not change any code. Reply in my language.

在改动任何东西之前，我们要用这个系统的真实数字给它做容量估算。用对生产数据库（或者完整的测试副本）和日志的只读访问权，去测量而不是去问：每张表的行数和按时间戳算出的每月增长、每个实体的事件数、从访问日志算出的峰值并发、今天的数据体量和五年后的预测，以及最慢的那些查询。给每个数字写一把量具（一个住在仓库里的脚本，带一个对着我会给你的已知案例的测试），并把每个数字连同产出它的命令展示给我；对每把量具做双向审计（该被数到的都数到了吗？数到的都真实存在吗？）。写 docs/VOLUME_SURVEY.md，每个数字标上 [数据库] 或 [日志]，并且只向我索要测不出来的东西：业务预期的增长，以及这个系统会不会服务于不止一个站点。然后写 docs/SIZING.md：如果一切都乘以十，最先坏掉的是什么；当前架构的哪些选择撑得住、哪些撑不住；以及我们现在、在演进之前要做哪些不对称决策，因为它们今天便宜、以后昂贵。不要改任何代码。用我的语言回复。

We are going to turn the normalization and the client's request for this stage into one queue of numbered pending items in docs/PENDING.md, each with its full specification as the method asks (number, title, node of the semantic tree, origin, description, business rules with decision and date or marked as missing, data in and out, screens, edge cases, acceptance criteria as given, when, then, how it will be verified, status). Sources for the normalization items: docs/AUDIT_[date].md, the discrepancies I decided to change, the screens that cannot be driven by a program, the secrets to rotate, the locks that are not implemented yet, and the decisions in docs/SIZING.md; each one keeps its speed mark: BLOCKS, PAID WHEN TOUCHED, or CAN WAIT. Sources for the client's items: the client's request for this stage; each one marked CORRECTIVE (something that fails today, with the way to reproduce it in the client's words) or EVOLUTIVE (something new). For every client item, list the normalization items that touch the same modules and should be paid together with it. If the request is ambiguous on any point such that you cannot write a verifiable item, ask me; do not resolve it by assuming. Order: blocking items first, then the client's items in the priority I gave you, each with its paired normalization. Reply in my language.

我们要把规范化和客户对这一阶段的请求，变成 docs/PENDING.md 里一条编号待办项的单一队列，每一条都带着方法要求的完整规格（编号、标题、语义树节点、来源、描述、带决定和日期的业务规则或标为缺失、进出的数据、界面、边界情况、以"给定、当、那么"形式写的验收标准、将如何验证、状态）。规范化待办项的来源：docs/AUDIT_[日期].md、我决定要改的那些不一致、不能由程序操作的那些界面、要轮换的密钥、还没实现的那些锁，以及 docs/SIZING.md 里的决策；每一条都保留它的速度标记： 阻塞、触及时偿还，或者可以等待。客户待办项的来源：客户对这一阶段的请求；每一条标为 纠正型（今天出错的东西，附上用客户的话写的复现方式）或演进型（新东西）。对每个客户待办项，列出那些触及同样模块、应该和它一起偿还的规范化待办项。如果请求在某一点上含糊到你写不出一条可验证的待办项，就问我；不要靠假设去解决它。顺序：先是阻塞的那些，然后是客户的那些，按我给你的优先级，每一条带着它配对的规范化待办项。用我的语言回复。

This pending item is a correction: [some patients receive the reminder twice and some receive none; three cases from last week are attached in the item]. Before changing anything: (1) Reproduce the failure with a test that drives the flow from the screen and checks the effect in the backend, and show me that it fails against the current code; that red is the proof that you reproduced the right defect. If you cannot reproduce it, tell me what you tried and what you need; do not fix what you cannot see. (2) Find the root cause and tell me in prose, with the evidence, before fixing. If the root cause is a business rule nobody wrote down, stop and ask me. (3) Fix at the root, not where it hurts, and nothing else: anything else you find goes to a pending item. (4) Show me the test green, the characterization suite still green, and the regression of the neighbouring items. (5) If the fix changes a current behaviour that someone may depend on, say so explicitly: that is a decision for me, not a side effect. Close the paired normalization items of this module in the same block, each with its own evidence. The commit message says "proved red against [version]" and the test counts. Reply in my language.

这条待办项是一次纠正：[有些患者收到两次提醒，有些一次都没收到；待办项里附了上周的三个案例]。在改动任何东西之前：（1）用一个从界面操作流程、并在后端验证效果的测试复现这次故障，并给我看它对着当前代码失败；那个红是你复现对了缺陷的证据。如果你复现不出来，告诉我你试过什么、你需要什么；不要去修你看不见的东西。（2）找出根因，并在修之前用散文连同证据告诉我。如果根因是一条没人写下来的业务规则，停下来问我。（3）在根上修，不要在疼的地方修，而且只修它：你发现的任何别的东西都进一条待办项。（4）给我看测试变绿、表征测试套件仍然是绿的，以及相邻待办项的回归。（5）如果这次修复改变了某个当前行为、而可能有人依赖它，明确说出来：那是我的一个决定，不是一个副作用。把这个模块里和它配对的规范化待办项在同一个功能块里关闭，每一条都带自己的证据。提交信息里写"对着[版本]先证红"以及测试的数字。用我的语言回复。