Architecture · 整体架构与组织设计
使各部分在明确的责任与关系下共同完成整体目的,并能随实践发展。架构的对象是那些
影响整体的选择:怎样分工,怎样接合,谁有权决定,哪些变化需要一起发生。目录、技能
分类和组织图只是表达;每部分都合理,不代表它们组合起来仍能完成工作。
从整体目的与现实矛盾出发
恢复服务对象、要达成的结果、已确认承诺和当前压力。区分根本目标、现有路线与偶然
安排;现状不能自动证明必要性,外部模式也不能代替自身判断。新设计先找真实需求,
已有体系 review 先找它实际服务的工作,而不从部门、模块或技能名称反推用途。
局部任务只恢复会影响判断的邻接关系。全体系 review 则先建立覆盖范围与轻量关系图,
再逐块深化,同时保留跨块链路的核对;不要将全量要求缩成几个方便的样本,也不为了
完整重建全部历史。优先处理决定整体效果的矛盾,不把所有局部偏好升格为架构原则。
恢复责任、权力与实际关系
按当前对象辨清:每部分承担什么,输入输出给谁,谁拥有权威事实与资源,谁能决定、
执行、接受结果和处理失败。标明实际观察、正式约定、候选设计与未知;一个名义 owner
没有对应能力、资源或授权时,责任并未落实。
区分职责、依赖、信息流、控制或决策、资源和生命周期。需要一起变化的内容不一定
需要同一个容器;放在一个容器内的内容也不一定共享权力与状态。领域不同,成立依据
不同:软件可由接口和运行机制约束,技能依靠发现与选择,人的协作还取决于沟通、
能力、动机和被接受的权责。不能凭类比宣称软件隔离、技能引用或组织治理已经成立。
组织整体,而非平均分配局部
按真实变化原因、协作频率、知识与资源分布划界。比较保留现状、合并、拆分、调整接口
或决策位置的实际代价;选择能支持需求的最小安排,不因可拆就新增层级、委员会、
服务或协调者。集中便于统一承诺,分散便于贴近信息,判断哪种决策需要哪种安排,
不用一个原则覆盖所有关系。
沿关键工作从输入追到最终结果,核对交界处的接纳、反馈与接续责任。谁判断局部结果
够不够,谁处理跨部分冲突,延迟或失败时谁能继续工作?正式接口之外的绕路和补偿
也属于现状证据;如果整体依靠别人重复录入、人工追踪或默契兜底,不能只报告图上分工清楚。
比较整体承担的负担:一处简化是否让另一处更难,一处效率是否降低整体完成能力,
新增统一层是否夺走必要的局部判断。必要复杂度可以保留;可行选择有分歧时给出决定
及理由,不用职责表或架构图代替取舍。缺少会改变方向的用户目标或授权才请求决定。
在变化与实践中检验
选择会改变方案的正常、冲突、失败或变化场景,推演各部分怎样合成最终结果。尤其
检查新增消费者、责任转交、资源短缺与目标变化是否让边界失效。按风险做最小验证;
推演、机械检查、实际观察与接受分别报告,不把漂亮结构或各块通过当成整体成立。
设计新体系时说明怎样从最小可用安排发展;重组已有体系时说明过渡期间谁承担原责任,
哪些身份、资料、承诺或未完成工作必须保留。沿已有 owner 和权威位置修改,不新增
第二套事实或永久总控来方便本次 review。设计组织不自动授权调整人员、发布制度,
设计产品也不自动授权部署或数据迁移。
交付让读者能重建选择:整体目的与当前压力,关键责任和关系,主要矛盾与替代方案,
推荐安排及代价,接合与演进方式,证据和未决问题。结果可以是有理由地维持现状;
不强制套图、评分或固定数量的层级与候选。
按对象深化
- 代码库、目录、模块、构建与运行边界:读 代码库设计。
混合语言、语言惯例和更细边界判断由该文按需展开。
- 整套 skills 的定位、覆盖、引用与归属:读 技能体系设计。
- 团队、岗位、长期协作与决策组织:读 组织设计。
只读当前对象所需的参考,不把不同领域统一成同一种边界或强制分层。
与相邻方法接合
本方法检查整体关系与体系覆盖,主 Agent 仍对当前任务综合负责;它不是所有设计工作
的前置审批。已有证据足够作出安排或局部修正时直接完成,不因问题跨了一个边界就
另起流程。只有下列专门判断仍未解决时,才按需深入相邻方法:
带入整体目标、局部问题、有效承诺与已有证据,带回会改变整体判断的结果;链接不自动
启用、不扩大权限,也不要求每个任务加载整套方法。相邻方法缺失时仍可交付当前架构
判断与具体缺口,不靠无限转向回避决定。
代码库与软件边界设计
在设计或评审目录、模块、构建、运行与交付关系时读取。本文保留代码库领域的具体方法;
整体目的、跨部分取舍与演进判断见本技能入口,不把软件的包、进程或数据库边界套用于其他组织。
这里解决“内容如何形成清晰结构”,而不只是“目录看起来整齐”。内容可以是代码、文档、配置、schema、生成物、package、module、crate、binary 或 service。
核心判断
- 不要先套用
src/、packages/、common/、shared/、utils/ 等目录模板。目录首先是导航;真实边界要由职责、依赖、构建、运行、状态和 ownership 关系共同支持。
- 先区分当前实现、目标设计、派生视图/生成物和历史依据。设计文档不能证明当前代码,目录名也不能证明独立发布或独立进程。
- “放一起”通常意味着有相同的变化原因、不变量、消费者、发布节奏、失败边界或 owner;“拆开”通常意味着其中至少一项可以独立变化,且边界能够被依赖、构建、运行或发布机制约束。
- 优先选择最小且可执行的边界:文件/目录 → private 或 internal unit → package/crate/module → binary/process → service/repository。不要因为理论上可拆就直接增加服务、仓库或中间层。
- 名称应说明所拥有的概念、面向的消费者和必要的角色/环境;
internal、public、api、core、common 等只是信号,除非有语言、构建或项目规则支持,不要把它们当作事实。
何时使用
- 决定新代码、文档、配置或生成物应放在哪个位置。
- 评审目录、模块、package、crate、Go module、workspace 或服务是否边界清楚。
- 判断两个已有单元应该合并、保持共置、拆成 package,还是拆成独立进程/仓库。
- 为跨 Node/TypeScript、Go、Rust、Python 或其他语言的项目建立 source、build、runtime 和 delivery 关系。
- 设计或修正模块、文件夹、公共 API、适配器、插件和平台实现的命名。
不要仅因为文件很多就使用本 skill;纯格式化、单纯运行故障排查、视觉布局或已确认的陈旧内容清理应交给更合适的工作流。若主要问题是残留、重复、分散或错位的既有责任,先明确目标结构,再使用适用的清理方法。
工作流程
1. 定义一个结构问题
把问题收敛成一个可以作出决定的问题,例如:
X 是同一功能的两个实现,还是两个不同消费者的边界?
- 这个目录是 source of truth、生成输出、发布镜像,还是仅用于构建?
Y 应该是当前 package 的内部实现、可复用 library,还是独立 process?
- 混合语言代码的公共契约在哪里,谁拥有它?
记录对象、目标、当前压力、明确约束和不在本次范围内的相邻问题。不要为了“完整”先绘制整个仓库。
2. 恢复会改变判断的关系
按需读取入口、消费者和维护说明,然后为候选对象建立最小关系表:
| 对象 | 拥有的职责/不变量 | 直接消费者与入口 | import/API/可见性 | build/version/delivery | runtime/state/owner |
至少把下面几类关系分开;一个关系成立不能替代另一个关系:
- source:文件、目录、生成输入和派生视图的来源。
- dependency/API:imports、exports、visibility、协议、注册和调用方向。
- build/version:package、crate、module、workspace、构建 target、版本与缓存边界。
- runtime/delivery:library、CLI、binary、process、container、installer 和部署组合。
- state:数据库、队列、事务、租约、缓存、恢复和资源 ownership。
- ownership/release:维护者、review 路径、兼容承诺、发布与回滚责任。
若问题涉及混合语言,读取 hybrid-repositories.md。若只是某种语言的 package 和构建惯例,读取 language-idioms.md。
3. 判断共置、拆分和边界强度
用变化原因、不变量、消费者、构建/发布、失败隔离和 ownership 逐项判断。若只有目录位置不同,但关系和生命周期相同,不要制造虚假的模块;若关系已经不同但仍共用一个“方便目录”,不要用目录共置掩盖边界。
先选择能够表达并约束当前差异的最小单元:
- 同一概念、同一状态和同一变化原因:优先同 package 或相邻目录。
- 只想隐藏实现:使用 private/internal 可见性或稳定 facade。
- 有稳定外部消费者、独立依赖或独立构建责任:考虑 library/package/crate/module。
- 有独立启动、资源、失败、部署、升级或回滚责任:才考虑 binary/process/service。
- 只有版本治理、权限、ownership 或发布节奏确实独立时,才考虑 repository。
具体判断表和边界反例见 decision-model.md。
4. 给概念命名并安排位置
- 先命名“它拥有什么”,再命名“它用什么技术实现”。优先使用领域概念、稳定协议或明确的角色。
- 只有确有两个不同实现或环境时才添加
client、server、adapter、protocol、runtime、cli、browser、node 等限定词。
- 用
internal 表示真实的不可对外依赖边界;不要仅凭下划线、目录名或 README 语气声称私有。
common、shared、misc、utils、manager、core 如果没有具体 owner、消费者和排除范围,通常是未完成的命名。
- 对每个名称做四个检查:它包含什么、明确排除什么、最近邻概念是什么、一个反例会落在哪里。
5. 处理混合架构
- 为 schema/IDL/proto 设定唯一 source of truth,明确 generator、generated output、提交策略和可重现验证。
- 把语言绑定、外部 provider、平台实现和协议转换放在边界 adapter;不要让 adapter 偷走核心状态或业务 ownership。
- 用构建选择和发布矩阵表达平台差异,并追踪每种组合最终生成的 artifact。
- 把 plugin、extension、contrib、router、app 和 package 与 process、service、distribution 分开判断;注册机制不自动提供进程隔离。
- 跨语言不等于必须合并或拆成多个仓库。先检查依赖、提交、版本、发布和 ownership 是否需要同一边界。
6. 验证并收束
选择能暴露当前边界问题的真实变更场景检验结构:新增同类功能、替换实现、引入第二个消费者、改变平台、独立发布、失败/重启或迁移。场景数量随未决问题而定,不将次数作为结构成立的依据。验证顺序可按风险调整,但报告必须分开:
- 结构事实:当前源码、manifest、import、构建配置和注册关系。
- 机械结果:格式、静态检查、类型检查、测试、构建、安装或打包。
- 运行时观察:入口、进程、协议、资源、失败和恢复行为。
- 用户验收:维护者能否定位、修改、测试、发布和理解这套结构。
若用户只要求评审,不修改文件;若用户要求重组,执行最小的完整改动,保留已有未提交工作,并在结束前复查状态和差异。详细报告模板见 review-and-evidence.md。
交付内容
返回一份能让别人重建决定的记录:
- 结构问题与范围。
- 当前关系证据和仍未知的关系。
- 共置/拆分/不改变的决定及理由。
- 建议的目录、模块、命名或边界图;明确哪些只是组织视图。
- API、构建、运行、状态和 ownership 的实际约束。
- 需要的最小改动、验证结果、未验证项和重新打开条件。
不要把漂亮的目录树、一次格式检查通过或模型的自我解释当成模块化、运行独立性或用户验收的证据。
Structure decision model
Read this reference when the task requires deciding whether material belongs together, should be split, or needs a stronger boundary.
Start with the object, not the container
An object may be a concept, source unit, package, build target, artifact, process, state owner, or public contract. A folder is only one possible view of those objects. Before proposing a move or split, answer:
- What responsibility or decision does this object own?
- What does it deliberately not own?
- Who consumes it, through which entrypoint or interface?
- Which changes should happen together, and which should not?
- Which invariant, transaction, resource, or failure behavior must remain local?
- What is public, private, generated, or only a build-time view?
- Who reviews, versions, publishes, deploys, and recovers it?
If these answers are missing, record the unknown instead of inventing a package boundary.
Six relations to inspect separately
| Relation | Evidence | Decision it can support | What it cannot prove alone |
| Semantic responsibility | domain rules, invariants, change reasons | grouping or splitting concepts | independent package or process |
| Dependency/API | imports, exports, visibility, protocol, registry | direction and public surface | independent deployment |
| Build/version | manifest, module/crate/package, target, workspace | build, cache, version or release unit | runtime isolation |
| Runtime/delivery | entrypoint, binary, container, process supervisor | process and deployment boundary | source ownership |
| State/resource | database, queue, transaction, lease, cache, filesystem | ownership and failure coupling | public API stability |
| Ownership/release | owner files, review rules, compatibility and rollout | governance and responsibility | implementation truth |
The same directory may contain multiple objects from different relations. Conversely, one semantic feature may intentionally span source directories, a schema file, generated code, a test fixture, and a release configuration.
Grouping signals
Keep units together when most of these are true:
- They change for the same reason and are reviewed together.
- They share an invariant, transaction, lifecycle, or resource owner.
- They have the same primary consumers and compatibility horizon.
- Splitting would create a protocol or coordination layer with no independent value.
- Their build, test, failure, deployment, and rollback boundaries are the same.
Co-location does not require exposing every symbol. A single package can have a stable facade and private implementation; a single process can contain several internal components.
Splitting signals
Split only when the difference is real and useful:
- A consumer needs one side without the other.
- The sides change, compile, test, release, or scale independently.
- They have different platform or dependency constraints.
- They need different failure, security, resource, or recovery boundaries.
- They have different owners or compatibility promises.
- A protocol or schema already exists and is the canonical boundary.
Do not split merely because a file is long, two languages appear, a folder has many children, or a future consumer is imagined without evidence.
Boundary ladder
Choose the lowest level that can enforce the required difference:
| Level | Use when | Evidence to check |
| File or subdirectory | material is one responsibility but benefits from navigation | imports, local cohesion, discoverability |
| Private/internal unit | implementation must be hidden from unrelated consumers | language/build visibility rules, facade |
| Package/crate/module | dependency, build, version, or consumer boundary is real | manifest, import path, build and test target |
| Library/package distribution | external reuse and compatibility are intentional | public API, release metadata, install behavior |
| Binary/process | independent lifecycle, resources, failure, or deployment matters | entrypoint, protocol, supervisor, artifact and rollback |
| Repository | governance, access, release cadence, or source-of-truth boundary is independent | ownership, CI, versioning, publication and migration |
An extra layer has a cost: names, APIs, coordination, testing, versioning, and failure modes. State why the current lower level cannot express or enforce the requirement before escalating.
Boundary tests
For every proposed unit, write short answers to:
- Include: what belongs here and why?
- Exclude: what looks nearby but must stay outside?
- Nearest neighbor: which other unit is easiest to confuse with it?
- Counterexample: what request would make the proposed boundary wrong?
- Consumer: who is allowed to depend on it, and through what surface?
- Change: what can change without changing this unit's contract?
If the answers are only directory names, the boundary is not yet specified.
Naming rules
Name by responsibility and stable relationship:
protocol, client, server, adapter, runtime, and cli are useful when the role is materially different.
- An environment suffix such as
browser, node, native, or wasm should correspond to a real build or runtime constraint.
- A concept name should not silently promise package publication, process independence, or public API stability.
common, shared, utils, misc, and core require a concrete contract and exclusion rule or should be decomposed.
Names are part of the interface. A rename that changes imports, persistence keys, plugin IDs, URLs, generated paths, or user commands is a contract change even when the implementation is unchanged.
Hybrid repository and architecture review
Read this reference when more than one language, build system, runtime, artifact type, or repository participates in one product.
Draw separate graphs
For each important unit, map the following rather than one combined tree:
| Graph | Questions |
| Source | Which files are authoritative source, generated output, vendor, mirror, fixture, or documentation? |
| Dependency/API | Who imports or calls it? What visibility, protocol, schema, or registration rule constrains the edge? |
| Build | Which target compiles, generates, links, packages, or tests it? Which target is only an aggregate/phony target? |
| Runtime/delivery | Which library, binary, process, container, installer, or distribution contains it? Can it start, stop, upgrade, and roll back independently? |
| State/resource | Which process owns data, queues, leases, files, credentials, transactions, and recovery? |
| Ownership/release | Who reviews the source, schema, generator, generated output, release configuration, and deployment? |
An implementation library can be independently compiled but statically linked into one process. A plugin can be dynamically discovered but share the host's lifecycle. A repository can contain several artifacts without providing independent release governance.
Source of truth and generated outputs
For every generated or mirrored object, record:
authoritative input → generator/version → generated output → consumer/build target → verification
Check whether output is committed, reproducible, ignored, published to another repository, or regenerated in CI. Never treat an automatically published mirror, generated/, out/, or vendor copy as authoritative without source evidence.
Schema and IDL need extra care:
- Give the schema one owner and one canonical location.
- Keep compatibility and versioning rules with the schema, not only with one generated language.
- Put language bindings and protocol adapters at the edge.
- Verify that generated code is consumed by the intended build targets and that stale output cannot silently become the API.
Platform and language boundaries
Organize platform code around the actual build/release matrix. For each platform, answer:
- Which source and target are selected?
- Which artifact is produced?
- Which API or ABI is exposed?
- Is the platform code a library, binding, tool, or part of one host process?
- Who tests and releases that combination?
Names such as linux, android, node, browser, native, or wasm are useful only when a build condition, target, runtime, or artifact makes the distinction real. Do not duplicate a core abstraction merely to mirror the platform directory.
Plugin, extension, application, and process
Classify each term by its enforced behavior:
- A package/crate is an import or build unit.
- A plugin/extension is an attachable implementation only if discovery, registration, lifecycle, and compatibility are defined.
- An application/CLI is an entrypoint and composition surface; it may still be one part of a larger process.
- A process/service has its own lifecycle, resource ownership, failure behavior, and deployment artifact.
- A distribution is a selected combination of components and configuration; it need not map one-to-one to a source directory.
Do not infer a process boundary from plugin, extension, contrib, app, server, or components. Check whether the unit is separately launched, addressed, upgraded, and recovered.
Repository split decision
Keep a mixed project together when atomic changes, shared CI, shared schema, synchronized releases, or cross-language refactors are important. Split repositories when source ownership, access, release cadence, compatibility, or dependency isolation are independently governed and the coordination cost is acceptable.
Before splitting, check:
- Can a stable protocol/schema replace direct source coupling?
- Can a consumer build and test against a versioned artifact?
- Who owns migrations, generated code, compatibility, security, and rollback?
- Does a split make local development, atomic fixes, and failure diagnosis materially worse?
- Is the proposed new repository actually a source of truth rather than a publish mirror?
Patterns observed in large projects
- LLVM distinguishes projects, runtimes, build targets, and distribution components through CMake and installation configuration.
- Chromium uses GN targets, visibility, dependency rules, process layers, generated Mojo bindings, and OWNERS;
components/ is not automatically a product or service.
- Kubernetes distinguishes source,
cmd binaries, Go modules, staging publication, generated APIs, and container artifacts.
- Envoy separates API, implementation, server executable, extensions, mobile library, and distribution combinations; extensions are often linked into one host.
- OpenTelemetry separates specification/proto, language implementations, Collector components, and generated distributions; receiver/exporter directories are plugin types, not deployment units.
These patterns support the graph model; they are not templates to copy. Scale, build tooling, release cadence, and ownership must be independently justified.
Language and ecosystem idioms
Read only when the current repository uses the relevant language or package/build system. These are boundary clues, not templates. Verify the current project's manifests and build configuration before applying them.
Node.js and TypeScript
package.json fields such as exports, imports, bin, files, and types can define public imports, internal aliases, CLI entrypoints, and published content more precisely than directory names.
- TypeScript project references express logical subprojects through build dependencies and declaration boundaries. A
packages/ directory without references, manifests, or consumers is only a naming convention.
- In Next.js, route groups and private folders can organize route source without changing the URL or exposing a route. A folder can therefore be organizational rather than an API boundary.
- Node.js itself separates public library surfaces,
lib/internal, native src, vendored dependencies, tests, tools, and docs. The public/internal distinction is supported by exports and documentation, not by internal alone.
Useful primary references: TypeScript project references, Next.js project structure, Node.js collaborator guide.
Go
- A Go module is a versioned collection of packages; a package is a directory-level import unit; a binary or service is a runtime/delivery unit. Keep these relations separate.
cmd/ conventionally holds executable entrypoints. The reusable behavior normally lives in packages, often under internal/ when external imports must be compiler-restricted.
internal/ has language-enforced import rules. pkg/ has no equivalent special enforcement; treat it as a project convention that requires evidence.
go.work and replace can support development composition without proving a production deployment or repository boundary.
- Split a module when external reuse, versioning, dependency isolation, or release ownership justifies it—not merely because a directory is large.
Useful primary references: Organizing a Go module, Go Modules Reference.
Rust
- Cargo packages and crates have concrete targets: library, binary, integration test, example, benchmark, build script, or proc-macro. Check
Cargo.toml and target declarations rather than inferring from src/.
- A workspace shares build/dependency coordination across packages. Workspace membership is not by itself a public API, independent process, or release promise.
- Features, target-specific dependencies, proc-macros, generated code, and platform modules often form real build boundaries even when the final artifact is one binary.
- Crate extraction is justified by API reuse, dependency/build isolation, platform constraints, release ownership, or a separately testable contract. Do not optimize for crate count.
Useful primary references: Cargo project layout, Cargo workspaces.
Python
src layout separates importable source from the checkout and makes installed-package behavior easier to test; flat layout reduces friction for direct checkout execution. Packaging metadata and development workflow decide which tradeoff is appropriate.
- A public facade, re-export, documented import path, entry point, and deprecation policy together define API stability. A leading underscore or
internal directory is only a signal.
- Plugins and applications need an actual discovery or registration mechanism, lifecycle, scope, and compatibility contract. A
plugins/ directory alone is not a plugin system.
- Django distinguishes framework package, project, reusable application, and management command. FastAPI's
APIRouter organizes routes within one application; it does not imply a service or distribution boundary.
- CPython shows that a runtime feature may span Python source, native implementation, tests, docs, and platform build files. Feature alignment can be more useful than forcing everything into one package tree.
Useful primary references: src layout vs flat layout, pytest integration practices, FastAPI bigger applications, CPython structure.
Cross-language cautions
- Ruff combines Rust implementation crates with Python distribution metadata; the Python import package, Rust workspace, wheel, and CLI are different objects.
- A protocol/schema can be the stable cross-language boundary while implementations remain in one repository or several repositories.
- Generated bindings are outputs of a source/build relation, not automatically public API or source of truth.
- A language-specific convention is transferable only when the current toolchain enforces the same relation. Do not copy names such as
cmd, internal, crates, src, or packages as decoration.
组织与长期协作设计
在设计或 review 团队、岗位、职能协作与决策关系时读取。对象是人怎样共同完成工作,
组织图不是运行事实;岗位名称也不能证明实际权力、能力与资源已经到位。
从真实工作看分工
从服务对象、结果与当前困难出发,追踪工作怎样发生、信息在哪里、谁作决定、谁实际
完成、谁接受以及谁承担后果。结合既有约定与具体案例,区分正式安排、实际协作和
未经核实的解释。人的动机或能力不能只凭角色标签推断,敏感判断保留证据范围。
看分工是否支持工作连续:专业知识、沟通负担、资源限制、任务量与变化频率怎样影响
结果?责任有无相应权力和时间,决策者能否取得所需信息?不要把组织问题一律归结为
“执行不力”,也不因存在协调成本就要求所有工作归同一个人。
权责、接口与反馈
划清哪些事由岗位独立判断,哪些要共同协商,哪些涉及整体承诺需要集中决定。明确
结果接受、冲突处理与资源分配,不把执行者、建议者、协调者和最终决定者混成一人。
共同讨论不等于共同拥有全部责任;一名负责人也不等于其他人无需提供判断。
接口可以是成果、承诺、协商渠道和反馈节奏,无须把每次交流变成工单、审批或协议。
说明等待、意见冲突、负荷过高或成员离开时工作怎样继续。非正式协作可能有效,先
理解它承担什么,再决定是否需要正式化;不能为了组织图整齐消除实际知识与信任。
比较按职能、产品、项目或其他实际关系组织的得失,不先套矩阵或层级模板。新管理层
或协调岗位必须对应当前无人承担的判断,不为观察进度就增加决策关口。局部效率提高
却加重跨团队等待,或责任下放却不给资源,都不算整体改善。
演进与证据
用真实协作案例检查方案,包括日常交付、意见冲突、优先级变化、关键成员缺席与交接。
推演可以指出风险;试行和参与者反馈才能支持实际效果判断。不能从软件依赖图推导
人员应当怎样工作,也不凭组织层数证明效率或公平。
说明变更中的原工作由谁接续、已有承诺与知识怎样保留,哪些安排可以小范围试行。
区分推荐方案、可逆试行与正式制度决定,按用户授权推进;设计任务不自动授权调整
人员、考核、任免或对外发布制度。
若只是安排一次有界任务的多人或多 Agent 分工,按需使用
divide-and-conquer;长期权责设计仍留在这里。
若缺的是外部组织理论的理解,使用 research-synthesis
核对原语境与迁移条件,不把理论流派直接当作本组织的制度。
交付说明工作与现实压力、推荐权责和协作关系、替代方案及代价、过渡与验证、需要
相关参与者确认的事实或决定。不要用岗位说明的数量代替工作链路与整体关系已经闭合。
Review, change, and evidence
Read this reference when the task requires a written architecture review, an actual reorganization, or a claim that a structure works in practice.
Choose the mode
Review only
Inspect the smallest set of files and configurations that can change the decision. Return findings, alternatives, evidence, unknowns, and reopen conditions. Do not move files or rewrite imports unless requested.
Reorganization requested
Define the target boundary first, then make the smallest complete change: source, imports, manifests, build/codegen, tests, documentation, registration, and release references that belong to the same contract. Preserve unrelated uncommitted work and do not delete data or an uncertain endpoint to make the tree cleaner.
Runtime or delivery claim
A structural review may identify a hypothesis, but it does not prove startup, packaging, isolation, recovery, or user acceptance. Use the project's runtime and integration checks for those claims and report the structural and runtime evidence separately.
Evidence ladder
| Level | What to inspect | What it supports |
| Source evidence | imports, exports, manifests, build files, codegen, entrypoints, ownership docs | current structural facts |
| Mechanical verification | formatter, linter, typecheck, unit/integration tests, build, package/install | conformance and repeatable mechanics |
| Runtime observation | clean import/install, CLI/service start, protocol call, process tree, failure/restart, artifact inspection | actual behavior in the exercised path |
| Boundary support | independent consumer/build/release/failure/ownership scenario | whether the proposed boundary is useful and enforceable |
| User acceptance | maintainers can locate, modify, test, release, and explain the result | practical success |
Do not upgrade a lower level into a higher one. A passing formatter does not prove a correct package boundary; a successful unit test does not prove an independent service; a generated directory does not prove source ownership.
Change scenarios
Use scenarios that can falsify the proposal:
- Add another feature in the same concept.
- Replace one implementation without changing consumers.
- Add a second consumer or language binding.
- Build or publish only one target/platform.
- Restart or fail one part while another continues.
- Change a schema, generated output, or public name.
- Review, version, roll back, or migrate the unit independently.
For each scenario, state what should remain local, what crosses the boundary, and what evidence would show that the proposal is wrong.
Compact report format
结构问题:<one concrete question and scope>
当前事实:<source, dependency, build, runtime, state, ownership evidence>
决定:<keep, move, split, merge, rename, or defer>
边界:<owns / excludes / consumers / enforced surface>
建议结构:<tree or relation view, with non-boundary folders marked>
验证:<mechanical, runtime, boundary, and acceptance evidence separately>
未知与重开条件:<what was not checked and what would change the decision>
If multiple options remain valid, compare their change cost, dependency direction, build/release cost, runtime isolation, ownership clarity, and migration risk. Do not hide an unresolved choice behind a confident folder tree.
技能体系设计与整体审查
在新建技能体系或 review 全部 skills 的架构时读取。对象是任务如何选择、组合与维护
方法;逐篇文字都通顺,只能证明局部表达,不能证明体系覆盖、分工与接合合理。
从任务恢复体系
明确体系服务谁、有哪些真实任务,以及通用、项目开发和产品运行等不同接收环境。
全量 review 清点范围内的技能与引用,先看选择描述、主要判断与交付,再深入有争议的
正文和资源。声明范围与排除理由,不能把同名引用当成独立维护副本,也不能漏掉不在
当前展示目录但参与发现或发布的来源。
用足以解释选择的关系记录:技能的任务压力、主要判断、输入与交付、最近邻、维护源
和使用环境。目录与主题标签是导航,不能单独证明技能应该存在或应该独立拆开。
区分可复用方法、工作角色、领域资料、项目操作流程与运行机制。角色可与方法配合,
无需强求同一种结构;资料可作为按需参考,不必独立成为 skill;runtime 保证不能因写成
指导就归技能所有。分类服务于判断,不创建统一模板或强制层级。
同时看覆盖与接合
从真实请求走向选择:有用的方法能否发现,最近邻描述能否区分,低风险任务是否被
误导去运行完整流程?再从技能回到任务:是否有独立判断,是否只是别的技能的包装,
是否抢了工具或项目指令的责任?没有消费者的候选保留为候选,不靠假想需求证明覆盖。
方法相似不等于重复。若相同请求需要分别跑两套调查、产出两份相同判断,或同一规则
在两处维护,就检查是否应归并;若对象、失败方式或交付不同,保留独立方法并澄清转向。
具体成立性、载体与表达判断按需使用
agent-guidance,整体审查复用其结果,不再发明第二套 skill 准入标准。
引用应说明哪个未决问题需要另一种方法、带入什么、带回什么。相互链接可以成立,
相互要求先完成对方则可能无法开工。检查自动加载与按需选择的区别、资源相对路径、
同名冲突和发布来源;链接有效不证明正文可被目标环境读取或行为已经改善。
整体能力缺口未必需要新技能,可能是缺输入、工具、权限、来源或接线。不得用“建立
总控技能”掩盖这些缺口,也不把复用关系一律做成依赖包管理或永久技能注册框架。
取舍与验证
给出保留、改写、合并、拆分、转为 reference 或修正发现入口等选择及依据。执行修改
须保全唯一维护源与实际消费者;来源、示例、元数据和引用一起切换,历史记录注明
当前入口,保留原来判断的语境。不要为了名称对称改变技能职责。
选择能区分最近邻的真实任务,检查发现、选择、按需深入和结果交还。全量架构 review
覆盖所有范围内对象,行为试验可针对有争议的边界,不要求逐技能跑相同脚本。独立代理
的阅读与选择检验可支持路由判断,不能替代真实环境的加载和任务效果观察。
交付整体能力与关系图景、最重要的缺口和重复根因、各对象处置及接合影响、修改与证据。
沿用当前记录,不另建永久技能台账;未核实的加载或效果明确保留未知。