ns-harness-architecture-rules

Original：🇺🇸 English

Translated

(NS) Generate or refresh lean architecture-rules.md for AI agents — stack, layout, patterns, constraints. Use when the user asks for architecture rules, .nextstage-harness/rules/architecture-rules.md, agent conventions, or "document how this repo works for the AI". Do NOT use for business specs (ns-harness-codebase-reverse-spec), brownfield maps (ns-harness-bootstrap-brownfield), or one-off Cursor rules without a full architecture pass.

2installs

Sourcenextstage-brasil/skills

Added on2026-08-14

NPX Install

npx skill4agent add nextstage-brasil/skills ns-harness-architecture-rules

SKILL.md Content

View Translation Comparison →

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.

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.

Harness discovery

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.

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

Workflow

Step 1 — Anchor and baseline

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.

Step 2 — Reconnaissance

Follow

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.

Step 3 — Extract architecture facts

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

.

Step 4 — Draft the constitution

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.

Step 5 — Write, sync, and report

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.

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.

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