ns-harness-architecture-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Rules Generator

架构规则生成器

Produce hot memory for coding agents: a single always-loaded

{harness_root}/rules/architecture-rules.md

that encodes how this repository is structured and which constraints agents must not violate.

This is not a business spec (

ns-harness-codebase-reverse-spec

) or an SDD planning artifact (

ns-harness-bootstrap-brownfield

). It is the constitution — loaded every session, kept lean, written for machine consumption with explicit paths and do/don't rules.

为编码Agent生成热内存：一个始终加载的

{harness_root}/rules/architecture-rules.md

文件，记录此代码库的结构以及Agent必须遵守的约束条件。

此文件不是业务规格说明（

ns-harness-codebase-reverse-spec

）或SDD规划工件（

ns-harness-bootstrap-brownfield

）。它是一份宪章——每次会话都会加载，保持精简，专为机器读取编写，包含明确的路径与禁止/允许规则。

Design principles

设计原则

Agent-first — file paths, entry points, forbidden zones, and test commands. Telegraphic tables/bullets; a developer skimming prose is not the audience.
Lean by default — target 80–200 lines (hard cap ~250). Depth belongs in scoped layer rules or
```
docs/
```
; this file routes to them.
Evidence-based — every rule must trace to something found in the repo. Mark
```
inferred
```
items; do not invent stack or patterns.
Load-bearing — agents trust this absolutely. Stale rules cause silent failures; prefer omission over guesswork.
Separation — universal architecture here; file-type or domain detail in sibling rules (
```
backend-rules.md
```
,
```
frontend-rules.md
```
, etc.).

See

../ns-harness/references/agent-artifact-compress.md

before every save, then

references/compression-guide.md

when the draft still exceeds the line budget.

Agent优先——包含文件路径、入口点、禁止区域和测试命令。采用简洁的表格/项目符号；目标受众不是浏览散文的开发人员。
默认精简——目标篇幅为80–200行（硬上限约250行）。详细内容应放在特定层级规则或
```
docs/
```
目录中；此文件仅负责引导至对应内容。
基于证据——每条规则必须能追溯到代码库中的实际内容。标记
```
inferred
```
（推断）项；不得凭空捏造技术栈或模式。
可信赖——Agent会完全信任此文件内容。过时的规则会导致无声故障；与其猜测，不如省略不确定的内容。
分离职责——通用架构放在此处；文件类型或领域细节放在同级规则文件（
```
backend-rules.md
```
、
```
frontend-rules.md
```
等）中。

每次保存前请参考

../ns-harness/references/agent-artifact-compress.md

，如果草稿仍超出行数限制，请参考

references/compression-guide.md

。

Harness discovery

Harness 发现

See

../ns-harness/references/harness-discovery.md

and

../ns-harness/references/rules-sync.md

Output path	When
`{harness_root}/rules/architecture-rules.md`	Default — canonical constitution
`{product_root}/.nextstage-harness/rules/architecture-rules.md`	Monorepo product folder is the harness anchor

Read

AGENTS.md

and existing

{harness_root}/rules/*.md

before scanning — reuse and link; do not duplicate sibling rules. Legacy:

.cursor/rules/*.mdc

only if

{harness_root}

is absent.

请查看

../ns-harness/references/harness-discovery.md

和

../ns-harness/references/rules-sync.md

。

输出路径	适用场景
`{harness_root}/rules/architecture-rules.md`	默认设置——标准宪章文件
`{product_root}/.nextstage-harness/rules/architecture-rules.md`	当单体仓库产品目录为Harness锚点时使用

在扫描前请先读取

AGENTS.md

和已有的

{harness_root}/rules/*.md

文件——复用并链接内容；不得重复同级规则中的内容。遗留规则：仅当

{harness_root}

不存在时，才使用

.cursor/rules/*.mdc

。

When to use

使用场景

Trigger	Action
New repo / first agent setup	Generate initial constitution
Major stack or layout change	Refresh in place
`architecture-rules.md` missing but other rules exist	Generate and cross-reference siblings
User says rules are stale or agents keep making same mistake	Refresh targeted sections

触发条件	对应操作
新代码库 / 首次Agent配置	生成初始宪章文件
技术栈或布局发生重大变更	更新现有宪章文件
`architecture-rules.md` 缺失但存在其他规则文件	生成宪章文件并关联同级规则
用户反馈规则过时或Agent反复犯相同错误	针对性更新相关章节

Workflow

工作流程

Step 1 — Anchor and baseline

步骤1 — 锚定与基线

Resolve
```
{harness_root}
```
,
```
{product_root}
```
.

Read

AGENTS.md

, existing

architecture-rules.md

, and list

{harness_root}/rules/*.md

Note gaps the user mentioned (if any) and whether this is create or refresh.

If the user did not specify scope, confirm once: whole repo vs

{product_root}

subtree.

确定
```
{harness_root}
```
和
```
{product_root}
```
路径。

读取

AGENTS.md

、已有的

architecture-rules.md

，并列出

{harness_root}/rules/*.md

文件。

记录用户提及的内容缺口（如有），以及本次操作是创建还是更新。

如果用户未指定范围，请确认一次：是针对整个代码库还是

{product_root}

子目录。

Step 2 — Reconnaissance

步骤2 — 侦察

references/reconnaissance-checklist.md

and

references/stack-signals.md

. Read-only — do not modify application code.

Minimum scan:

Root manifests (

package.json

composer.json

pyproject.toml

go.mod

Cargo.toml

docker-compose.yml

, etc.).

Directory tree (~2 levels under
```
{product_root}
```
).
Entry points (HTTP routers,
```
index.php
```
,
```
main.ts
```
, CLI commands, workers).
Module/domain folders and generated or build directories (never-edit zones).
Test layout and how tests are run (scripts, Docker, CI snippets).
Existing docs under
```
docs/
```
,
```
README.md
```
.

Checkpoint (recommended): Present a short recon map (stack, layout, modules, generated zones, test command) and ask the user to confirm or correct before drafting. Skip only on explicit autonomous run.

遵循

references/reconnaissance-checklist.md

和

references/stack-signals.md

。仅读取——请勿修改应用代码。

最低扫描范围：

根目录清单文件（

package.json

、

composer.json

、

pyproject.toml

、

go.mod

、

Cargo.toml

、

docker-compose.yml

等）。

目录树（
```
{product_root}
```
下约2层深度）。
入口点（HTTP路由、
```
index.php
```
、
```
main.ts
```
、CLI命令、工作进程）。
模块/领域目录以及生成或构建目录（不可编辑区域）。
测试布局和测试运行方式（脚本、Docker、CI片段）。
```
docs/
```
下的现有文档和
```
README.md
```
。

**检查点（推荐）：**展示简短的侦察映射（技术栈、布局、模块、生成区域、测试命令），并请用户确认或修正后再开始起草。仅在明确要求自动运行时可跳过此步骤。

Step 3 — Extract architecture facts

步骤3 — 提取架构事实

Turn evidence into agent-actionable rules:

Category	What to capture
Scope	Product root, monorepo vs standalone, where specs and agent assets live
Stack	Languages, frameworks, DB, cache, queue, local URLs/ports when discoverable
Layout	Folder tree (abbreviated), module boundaries
Patterns	API style, multitenancy, auth, module conventions, integration boundaries
Forbidden	Generated dirs, migration constraints, secrets locations
Dev & test	Docker services, test container name, copy-pasteable test commands (behavioral rules stay in `AGENTS.md` )
Discipline	Language for code/docs vs user chat, minimal diff, completion style — only if present in repo rules or `AGENTS.md`

For large subsystems, do not inline — add one line pointing to a dedicated layer rule and offer to generate that sibling in a follow-up. Sibling creation:

npx @nextstage-brasil/harness add-rule <name> --description "…"

(default

alwaysApply: false

). Never hand-write

.cursor/rules/*.mdc

or omit

cursor.description

/ apply mode in

manifest.json

— see

../ns-harness/references/rules-sync.md

将证据转化为Agent可执行的规则：

类别	需捕获的内容
范围	产品根目录、单体仓库/独立仓库、规格说明和Agent资产的存放位置
技术栈	编程语言、框架、数据库、缓存、队列、可发现的本地URL/端口
布局	目录树（简化版）、模块边界
模式	API风格、多租户、认证、模块约定、集成边界
禁止操作	生成目录、迁移约束、密钥存储位置
开发与测试	Docker服务、测试容器名称、可直接复制粘贴的测试命令（行为规则保留在 `AGENTS.md` 中）
规范	代码/文档使用的语言与用户聊天语言的区分、最小化差异、完成风格——仅当代码库规则或 `AGENTS.md` 中有相关规定时才记录

对于大型子系统，请勿内联详细内容——添加一行指向专用层级规则的链接，并提议在后续步骤中生成该同级规则。创建同级规则：

npx @nextstage-brasil/harness add-rule <name> --description "…"

（默认

alwaysApply: false

）。切勿手动编写

.cursor/rules/*.mdc

或在

manifest.json

中省略

cursor.description

/应用模式——请查看

../ns-harness/references/rules-sync.md

。

Step 4 — Draft the constitution

步骤4 — 起草宪章文件

Use

references/architecture-rules.template.md

as the skeleton.

No YAML frontmatter in the canonical file — adapter metadata lives in

.nextstage-harness/manifest.json

Writing rules:

Prefer tables and bullet lists over paragraphs.
Use MUST / MUST NOT only for constraints that prevent real breakage; explain why in a few words when non-obvious.
End with Key references — table mapping topic → file path (specs, sibling rules,
```
AGENTS.md
```
).
English only in the output file.

Pre-save (mandatory): apply

../ns-harness/references/agent-artifact-compress.md

(caveman ultra), then

references/compression-guide.md

if still over budget. Write only the compressed draft.

以

references/architecture-rules.template.md

为框架。

标准文件中不得包含YAML前置元数据——适配器元数据存放在

.nextstage-harness/manifest.json

中。

规则编写要求：

优先使用表格和项目符号，而非段落。
仅对会导致实际故障的约束使用必须/禁止；当规则不明显时，用几句话解释原因。
结尾添加关键参考——表格映射主题→文件路径（规格说明、同级规则、
```
AGENTS.md
```
）。
输出文件仅使用英文。

**保存前强制步骤：**应用

../ns-harness/references/agent-artifact-compress.md

（极简压缩），如果仍超出行数限制，再应用

references/compression-guide.md

。仅保存压缩后的草稿。

Step 5 — Write, sync, and report

步骤5 — 写入、同步与报告

Write

{harness_root}/rules/architecture-rules.md

(or

{product_root}/.nextstage-harness/rules/...

) — compressed agent hot memory only.

Ensure

architecture-rules

exists in

.nextstage-harness/manifest.json

with

cursor.alwaysApply: true

and

claude.paths: null

Run
```
npx @nextstage-brasil/harness sync
```
(or instruct the user to run it) to regenerate adapters.
Do not modify application source unless the user explicitly asked.
Report briefly (3–6 bullets): what was detected, line count, new vs updated sections, suggested sibling rules still missing.

If a previous

architecture-rules.md

existed, mention what was removed, merged, or deferred to other files.

写入

{harness_root}/rules/architecture-rules.md

（或

{product_root}/.nextstage-harness/rules/...

）——仅保存压缩后的Agent热内存内容。

确保

.nextstage-harness/manifest.json

中存在

architecture-rules

，且

cursor.alwaysApply: true

、

claude.paths: null

。

运行
```
npx @nextstage-brasil/harness sync
```
（或指导用户运行）以重新生成适配器。
请勿修改应用源代码，除非用户明确要求。
简要报告（3–6个项目符号）：检测到的内容、文件行数、新增/更新的章节、建议补充的同级规则。

如果之前存在

architecture-rules.md

，请提及删除、合并或移至其他文件的内容。

Refresh mode

更新模式

When updating an existing file:

Preserve stable sections the user may have hand-edited (communication locale, GitLab MCP server name, protected branches) unless recon proves them wrong.
Replace stack/layout/modules from current evidence.
Drop rules that no longer match the codebase; add a
```
## Changelog
```
comment block at the bottom only if the user asked for audit trail — otherwise omit.

更新现有文件时：

保留用户可能手动编辑过的稳定章节（通信语言、GitLab MCP服务器名称、受保护分支），除非侦察结果证明内容错误。
用当前证据替换技术栈/布局/模块内容。
删除不再符合代码库的规则；仅当用户要求审计跟踪时，在底部添加
```
## Changelog
```
注释块——否则省略。

Quality bar (self-check before save)

质量标准（保存前自检）

```
agent-artifact-compress.md
```
applied (caveman ultra; no essay prose)
Canonical file has no YAML frontmatter

manifest.json

has

architecture-rules