project-memory-and-code-simplification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project-Memory and Code Simplification

项目记忆与代码简化

Overview

概述

Reduce real surface area rather than merely reducing line count. Leave one correct rule, representation, and documentation home that a future maintainer can understand and verify.

Treat code and project-memory as separate surfaces with the same discipline: identify the owner, prove the current contract, replace the cause of the complexity, and verify the resulting system. This is guidance, not a deletion quota or a mechanical checklist.

The candidate-evidence approach is inspired by DeepSeek Harness’s dsh-find-simplifications skill, while this workflow avoids Harness-specific packages, Agent Notes, and tooling assumptions.

减少真实表面积，而不仅仅是减少行数。留下一个正确的规则、表示和文档归属地，让未来的维护者能够理解和验证。

将代码和项目记忆视为具有相同纪律的独立表面：确定所有者，证明当前契约，替换复杂性的成因，并验证结果系统。这是指导，不是删除配额或机械检查清单。

候选证据方法受到 DeepSeek Harness 的 dsh-find-simplifications skill 的启发，而本工作流避免使用 Harness 特定的包、Agent Notes 和工具假设。

When to Use

何时使用

Working code is difficult to read, extend, or verify because it contains dead paths, repeated logic, speculative abstractions, redundant state, or hand-rolled infrastructure.
A code or documentation change accumulated conditionals, exception layers, or explanatory patches instead of correcting the owning rule.
docs/project-memory contains duplicated facts, misplaced explanations, reasoning transcripts, stale caveats, or double-negation prose.
A scoped task asks to simplify code and its project-memory explanation together.

Do not use this skill to initialize, migrate, or repair a project-memory schema or discovery marker. Use the project-memory-init skill for initialization and discovery configuration. Use the project-architecture-sync skill when completed implementation requires a new or changed durable architecture, domain, operations, or ADR fact. Use normal feature work for a new product behavior whose desired contract is not already explicit.

可工作的代码难以阅读、扩展或验证，因为它包含死路径、重复逻辑、投机性抽象、冗余状态或手写基础设施。
代码或文档变更累积了条件、异常层或解释性补丁，而不是修正所属规则。
docs/project-memory 包含重复的事实、错位的解释、推理过程记录、过时的警示或双重否定表述。
一个范围明确的任务要求同时简化代码及其项目记忆说明。

不要使用本 skill 来初始化、迁移或修复项目记忆 schema 或发现标记。使用 project-memory-init skill 进行初始化和发现配置。当已完成的实现需要新的或变更的持久架构、领域、运维或 ADR 事实时，使用 project-architecture-sync skill。对于期望契约尚未明确的新产品行为，使用正常的功能开发工作。

Core Principles

核心原则

Establish the owner before changing the symptom. A local workaround that preserves an incorrect owner or rule is not a simplification.
Prove consumers before removing a surface. A search hit, a missing static call site, or a passing test alone does not establish that an interface is unused.
Preserve every relevant proposition. Simplify wording and structure while retaining actors, conditions, ordering, ownership, side effects, failures, and consequences.
Replace an incorrect rule directly. Put the correct logic in the authoritative code path or documentation record, then remove obsolete branches, caveats, and duplicate explanations.
Write affirmative prose. State who acts, when, what happens, and the result. Replace double negatives with a direct condition, scope, or outcome.

在改变症状之前确定所有者。保留错误所有者或规则的局部变通方法不是简化。
在移除表面之前证明消费者。单独一个搜索命中、缺失的静态调用点或通过的测试并不能证明接口未被使用。
保留所有相关命题。简化措辞和结构，同时保留参与者、条件、顺序、所有权、副作用、失败和后果。
直接替换不正确的规则。将正确逻辑放入权威代码路径或文档记录中，然后移除过时的分支、警示和重复解释。
写肯定的表述。说明谁在何时行动、发生什么以及结果。用直接的条件、范围或结果替换双重否定。

Workflow

工作流

1. Establish the scope and authority

1. 确定范围与权威

Require a concrete code path, project-memory path, or both. Do not infer a repository-wide cleanup from a broad request.

Read the applicable repository instructions, neighboring code, tests, and documentation conventions. For project-memory work, read the target project’s docs/project-memory/SCHEMA.md, INDEX.md, and only the records relevant to the requested scope. Treat the target schema as the authority for record ownership, metadata, indexes, sources, language, and historical-record rules.

For code work, resolve unfamiliar project concepts from the wiki and code before asking the user, and read global and relevant real_arch hard rules. Preserve their exact approved meaning, scope, and authority during editorial cleanup. A changed obligation requires a separately reviewed hard-rule draft through the target memory policy; code behavior alone cannot override it. Do not turn simplification or completed implementation into an automatic factual wiki sync.

Classify each requested change as one of the following:

Behavior-preserving code simplification.
Approved correction of an already defined behavior.
Editorial project-memory consolidation that preserves verified facts.
A factual project-memory update that belongs to project-architecture-sync.

Stop and ask for direction when the desired behavior or authority is unclear.

要求具体的代码路径、项目记忆路径，或两者皆有。不要从宽泛请求中推断仓库级清理。

阅读适用的仓库说明、相邻代码、测试和文档约定。对于项目记忆工作，阅读目标项目的 docs/project-memory/SCHEMA.md、INDEX.md，以及仅与请求范围相关的记录。将目标 schema 视为记录所有权、元数据、索引、来源、语言和历史记录规则的权威。

对于代码工作，在询问用户之前先从 wiki 和代码中解决不熟悉的项目概念，并阅读全局和相关 real_arch 硬规则。在编辑清理期间保留其精确的已批准含义、范围和权威。变更的义务需要通过目标记忆策略进行单独审查的硬规则草稿；仅凭代码行为不能覆盖它。不要将简化或已完成的实现变成自动的事实性 wiki 同步。

将每个请求的变更分类为以下之一：

保留行为的代码简化。
已定义行为的已批准修正。
保留已验证事实的编辑性项目记忆整合。
属于 project-architecture-sync 的事实性项目记忆更新。

当期望行为或权威不明确时，停下来询问方向。

2. Map candidates to their causes

2. 将候选映射到其成因

For code, look for evidence of:

dead functions, branches, configuration, events, options, packages, or test-only public surfaces;
two representations of the same state, repeated validation, duplicated lifecycle tracking, or mirrored error handling;
interfaces or abstractions with no meaningful production consumer;
speculative generality that protects a future scenario instead of a current requirement; and
hand-rolled utilities that a supported language feature, standard library, or well-maintained dependency can replace with net deletion.

For project-memory, look for:

one fact stated in several records instead of its schema-defined home;
a caveat or amendment that compensates for an incorrect paragraph or section structure;
implementation narration, task history, duplicated rationale, or inventories that do not preserve a durable contract;
wording that obscures the active rule through nested exceptions or double negatives; and
links, indexes, or Sources fields that no longer match the owner record.

For every candidate, name the current owner, consumers, invariant or contract, and the smaller correct end state. Do not treat a large file or an unfamiliar abstraction as evidence by itself.

对于代码，寻找以下证据：

死函数、分支、配置、事件、选项、包或仅测试的公共表面；
同一状态的两种表示、重复验证、重复的生命周期跟踪或镜像错误处理；
没有有意义的生产消费者的接口或抽象；
保护未来场景而非当前需求的投机性通用性；以及
手写工具，而受支持的语言特性、标准库或维护良好的依赖可以用净删除替换。

对于项目记忆，寻找：

一个事实在多个记录中陈述，而不是在其 schema 定义的归属地；
为补偿不正确的段落或章节结构而添加的警示或修正；
不保留持久契约的实现叙述、任务历史、重复理由或清单；
通过嵌套异常或双重否定模糊主动规则的措辞；以及
不再匹配所有者记录的链接、索引或 Sources 字段。

对于每个候选，命名当前所有者、消费者、不变量或契约，以及更小的正确终态。不要将大文件或不熟悉的抽象单独视为证据。

3. Prove or reject the candidate

3. 证明或拒绝候选

Search exact symbols, strings, configuration keys, events, and wire values before editing. Read each relevant call site and distinguish production consumers from tests, documentation, fixtures, generated artifacts, and examples that may still be live smoke paths. Inspect dynamic registration, reflection, configuration loading, serialization, public APIs, and build tooling when they could hide a consumer.

For project-memory, distinguish editorial shape from factual content. Preserve valid metadata, resolving Sources links, lifecycle status, exact identifiers, and verified historical rationale. A fact that is absent, outdated, ambiguous, or contradicted by completed implementation requires the project-architecture-sync workflow instead of an editorial guess.

Reject or defer a candidate when removal changes a public contract without explicit approval, defeats a documented intentional boundary, relocates the same complexity behind a new wrapper, or lacks enough evidence to establish safety.

在编辑之前搜索精确符号、字符串、配置键、事件和线上值。阅读每个相关调用点，区分生产消费者与测试、文档、夹具、生成产物以及可能仍是活动冒烟路径的示例。检查动态注册、反射、配置加载、序列化、公共 API 和构建工具，当它们可能隐藏消费者时。

对于项目记忆，区分编辑形状与事实内容。保留有效元数据、解析 Sources 链接、生命周期状态、精确标识符和已验证的历史理由。缺失、过时、模糊或被已完成实现矛盾的事实需要 project-architecture-sync 工作流，而不是编辑性猜测。

当移除会改变公共契约而未经明确批准、破坏有记录的有意边界、将相同复杂性重新定位到新包装器后面、或缺乏足够证据确立安全性时，拒绝或推迟候选。

4. Design the direct replacement

4. 设计直接替换

For code, choose the smallest design that owns the rule once. Replace a wrong predicate, state model, or control path at its source; remove the obsolete branch, adapter, or duplicate representation in the same scoped change. Preserve externally observable behavior unless the user explicitly approved a correction and supplied or accepted the target behavior.

For project-memory, put each retained proposition in the schema-defined record that owns it. Rewrite the incorrect canonical passage directly, move duplicate material only when its evidence and metadata remain valid, repair affected indexes and links, then remove the downstream patch text. Update the source of generated text rather than editing a derivative artifact.

Keep project-memory structure intact: leave SCHEMA.md, docs/agents/project-memory.md, discovery markers, runtime state, and historical ADR decisions to their owning workflows. Preserve the target project’s Chinese-first policy for human-facing records and keep paths, code symbols, metadata keys, commands, and source excerpts exact.

对于代码，选择最小的设计，一次拥有该规则。在源头替换错误的谓词、状态模型或控制路径；在同一范围变更中移除过时的分支、适配器或重复表示。保留外部可观察行为，除非用户明确批准修正并提供了或接受了目标行为。

对于项目记忆，将每个保留的命题放入拥有它的 schema 定义记录中。直接重写不正确的规范段落，仅在重复材料的证据和元数据仍然有效时移动它，修复受影响的索引和链接，然后移除下游补丁文本。更新生成文本的来源，而不是编辑派生产物。

保持项目记忆结构完整：将 SCHEMA.md、docs/agents/project-memory.md、发现标记、运行时状态和历史 ADR 决策留给其所属工作流。保留目标项目面向人类记录的中文优先策略，并保持路径、代码符号、元数据键、命令和来源摘录的精确性。

5. Write concise affirmative documentation

5. 编写简洁肯定的文档

Express each rule as actor, condition, action, and outcome. Prefer a positive scope such as “Only verified records enter the index” over a layered prohibition that explains what does not happen under several exceptions.

Replace double-negative forms such as “not uncommon,” “not without,” “cannot fail to,” “不能不,” and “并非不” with the direct proposition they imply. Use one explicit negative guarantee only when it preserves a required security, compatibility, or safety boundary that an affirmative form cannot state faithfully.

Keep one explanatory home for architecture, rationale, or history. Repeat only the local contract a reader needs at the point of use. Remove prose that narrates the editing process, repeats code or metadata, or preserves a superseded workaround.

将每条规则表达为参与者、条件、行动和结果。优先使用积极范围，如“只有经过验证的记录进入索引”，而不是分层禁令，解释在几种例外下不会发生什么。

替换双重否定形式，如“not uncommon”、“not without”、“cannot fail to”、“不能不”和“并非不”，用它们暗示的直接命题。仅当肯定的形式无法忠实陈述所需的安全、兼容性或边界保证时，才使用一个明确的否定保证。

为架构、理由或历史保留一个解释性归属地。只重复读者在使用点需要的局部契约。移除叙述编辑过程、重复代码或元数据、或保留已被取代的变通方法的散文。

6. Apply and verify incrementally

6. 增量应用与验证

Change one coherent cause at a time. For code, run the narrowest relevant checks after each meaningful change and widen validation only when evidence requires it. For project-memory, verify the edited record’s metadata, Sources, relative links, indexes, terminology, and applicable schema consistency rules.

Review the whole diff after the local checks. Confirm that the result contains the correct owner, fewer live representations, no residual patch layer, and no unintended project-memory factual change. Report the inspected scope, changes, deliberately retained cases, deferred factual updates, and checks actually run.

一次更改一个连贯的成因。对于代码，在每次有意义的更改后运行最窄的相关检查，仅在证据要求时扩大验证。对于项目记忆，验证被编辑记录的元数据、Sources、相对链接、索引、术语和适用的 schema 一致性规则。

在局部检查后审查整个差异。确认结果包含正确的所有者、更少的活动表示、无残留补丁层，以及无意外项目记忆事实变更。报告检查的范围、变更、有意保留的案例、推迟的事实更新以及实际运行的检查。

Common Rationalizations

常见合理化

Rationalization	Reality
“No static call site means this surface is dead.”	Dynamic loading, public APIs, configuration, and smoke paths can be consumers. Classify them before removal.
“A new exception is safer than replacing the old rule.”	An exception preserves the wrong model and adds another maintenance path. Correct the authoritative rule and verify its contract.
“A shorter project-memory record must be clearer.”	A concise record still carries its complete verified proposition, Sources, ownership, and consequence.
“The facts are probably current, so editorial cleanup can fix them.”	An unverified factual change belongs to project-architecture-sync, which gathers durable evidence and requires approval.
“Double negatives retain useful nuance.”	State the actual condition or outcome directly; direct assertions are easier to verify and maintain.

合理化	现实
“没有静态调用点意味着该表面是死的。”	动态加载、公共 API、配置和冒烟路径可能是消费者。在移除前对它们进行分类。
“新异常比替换旧规则更安全。”	异常保留了错误的模型并增加了另一条维护路径。修正权威规则并验证其契约。
“更短的项目记忆记录必然更清晰。”	简洁的记录仍然承载其完整的已验证命题、Sources、所有权和后果。
“事实可能是当前的，所以编辑清理可以修复它们。”	未经验证的事实变更属于 project-architecture-sync，它收集持久证据并要求批准。
“双重否定保留了有用的细微差别。”	直接陈述实际条件或结果；直接断言更易于验证和维护。

Red Flags

红旗

Deleting a symbol, package, field, event, or test because a single search found no consumer.
Adding a guard, fallback, comment, or exception layer instead of correcting the owning rule.
Modifying tests solely to make a changed behavior appear preserved.
Moving project-memory prose without preserving its Sources, metadata, links, indexes, or schema-defined authority.
Editing SCHEMA.md, the reader protocol, discovery markers, runtime state, or ADR rationale during an editorial simplification.
Replacing a direct statement with a double negative, vague passive voice, or a chain of exceptions.
Expanding a local request into a repository-wide refactor without explicit scope.

因为单次搜索未找到消费者而删除符号、包、字段、事件或测试。
添加守卫、回退、注释或异常层，而不是修正所属规则。
仅修改测试以使更改的行为看起来被保留。
移动项目记忆散文而不保留其 Sources、元数据、链接、索引或 schema 定义的权威。
在编辑性简化期间编辑 SCHEMA.md、读者协议、发现标记、运行时状态或 ADR 理由。
用双重否定、模糊被动语态或异常链替换直接陈述。
在没有明确范围的情况下将局部请求扩展为仓库级重构。