ns-harness-architecture-rules

架构规则生成器

为编码 Agent 生成热记忆：一个始终加载的 {harness_root}/rules/architecture-rules.md，用于说明此代码库的结构，以及 Agent 必须遵守的约束。

这不是业务规范（ns-harness-codebase-reverse-spec），也不是 SDD 规划产物（ns-harness-bootstrap-brownfield）。它是宪章——每次会话都会加载，内容精简，明确列出路径和该做／不该做的规则，便于机器读取。

设计原则

1. Agent 优先——文件路径、入口、禁止访问区域和测试命令。采用电报式表格／项目符号；面向的不是快速浏览散文的开发者。
2. 默认精简——目标为 80–200 行（硬上限约为 250 行）。详细内容应放在分层规则或 docs/ 中；此文件负责指引。
3. 基于证据——每条规则都必须有代码库中的依据。将 inferred 项目标注出来；不要编造技术栈或模式。
4. 承重性——Agent 会绝对信任这些规则。过时的规则会导致无声故障；宁可省略，也不要猜测。
5. 职责分离——通用架构规则放在此处；文件类型或领域细节放在同级规则文件中（backend-rules.md、frontend-rules.md 等）。

每次保存前，请先查看 ../ns-harness/references/agent-artifact-compress.md；若草稿仍超出行数预算，再查看 references/compression-guide.md。

Harness 发现

请参阅 ../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。

适用时机

触发条件	操作
新代码库／首次配置 Agent	生成初始宪章
技术栈或布局发生重大变化	原位刷新
缺少 architecture-rules.md，但已有其他规则	生成并交叉引用同级规则
用户指出规则已过时，或 Agent 反复犯同一种错误	刷新相关部分

工作流

步骤 1——锚定并建立基线

1. 确定 {harness_root}、{product_root}。
2. 阅读 AGENTS.md、现有的 architecture-rules.md，并列出 {harness_root}/rules/*.md。
3. 记录用户提到的缺口（如有），以及此任务是新建还是刷新。

如果用户未指定范围，请确认一次：整个代码库，还是 {product_root} 子树。

步骤 2 — 侦察

按照 references/reconnaissance-checklist.md 和 references/stack-signals.md 操作。只读——不要修改应用代码。

最低限度的扫描：

1. 根目录清单（package.json、composer.json、pyproject.toml、go.mod、Cargo.toml、docker-compose.yml 等）。
2. {product_root} 下约 2 层的目录树。
3. 入口点（HTTP 路由器、index.php、main.ts、CLI 命令、工作进程）。
4. 模块／领域目录，以及生成或构建目录（禁止编辑区域）。
5. 测试布局及测试运行方式（脚本、Docker、CI 片段）。
6. docs/、README.md 下的现有文档。

检查点（建议）： 提供简短的侦察概览（技术栈、布局、模块、生成目录、测试命令），并请用户确认或更正后再起草。仅在明确要求自主运行时跳过。

步骤 3 — 提取架构事实

将证据转化为可供 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。

步骤 4 — 起草规范

使用 references/architecture-rules.template.md 作为框架。

规范文件中不要包含 YAML frontmatter——适配器元数据存放在 .nextstage-harness/manifest.json 中。

写作规则：

• 优先使用表格和项目符号列表，而不是段落。
• 仅对会造成实际故障的约束使用 MUST / MUST NOT；若原因不明显，用几个词说明原因。
• 以 Key references 结尾——用表格将主题映射到文件路径（规范、同级规则、AGENTS.md）。
• 输出文件仅使用英文。

**保存前（必须）：**先应用 ../ns-harness/references/agent-artifact-compress.md（极限精简风格）；如果仍超出预算，再应用 references/compression-guide.md。只写入精简后的草稿。

步骤 5 — 编写、同步并报告

1. 编写 {harness_root}/rules/architecture-rules.md（或 {product_root}/.nextstage-harness/rules/...）——仅存放压缩后的 Agent 热记忆。
2. 确保 .nextstage-harness/manifest.json 中存在 architecture-rules，且 cursor.alwaysApply: true、claude.paths: null。
3. 运行 npx @nextstage-brasil/harness sync（或告知用户运行），以重新生成适配器。
4. 除非用户明确要求，否则不要修改应用源代码。
5. 简要报告（3–6 条）：检测到的内容、行数、新增与更新的章节、仍缺失的建议同级规则。

如果先前存在 architecture-rules.md，请说明哪些内容已删除、合并或移至其他文件。

刷新模式

更新现有文件时：

1. 保留用户可能手动编辑过的稳定章节（沟通语言环境、GitLab MCP 服务名称、受保护分支），除非重新核查证明它们有误。
2. 根据当前证据替换技术栈、布局和模块。
3. 删除不再符合代码库现状的规则；只有用户要求保留审计记录时，才在底部添加 ## Changelog 注释块，否则省略。

质量标准（保存前自检）

• 已应用 agent-artifact-compress.md（极度精简；不写长篇说明）
• 规范文件没有 YAML frontmatter
• manifest.json 中的 architecture-rules 设置了 alwaysApply: true
• 行数 ≤ 250（最好 ≤ 200）
• 每个技术栈条目均已根据清单或配置核实
• 如存在，则列出生成路径／禁止路径
• 检测到 Docker／CI 时，测试命令可直接复制粘贴运行
• 存在独立测试容器／服务时，约定中记录测试服务名称和命令（而非开发容器或主机）
• 不重复同级规则的完整内容——仅提供链接
• 不包含业务领域规则（此类规则应放在 docs/specs/ 中）
• 已运行 harness sync，或已告知用户运行

相关技能

• ns-harness-bootstrap-brownfield — 用于 SDD 规划的 brownfield-map.md（范围更广，侧重规划）
• ns-harness-codebase-reverse-spec — 与技术栈无关的业务行为
• ns-harness — 工件路径和门禁约定