rulesmith (Csaba Kovacs)

rulesmith

   

为什么是rulesmith？

AI编码助手功能强大——直到你把它们指向一个真正的 生产代码库。然后他们产生了文件夹结构的幻觉，忽略了 您的约定，并生成看起来正确但不正确的代码 属于你的项目。

rulesmith的存在是因为我厌倦了在严肃的环境中照顾人工智能 代码库。

它分两个阶段工作：首先，它扫描您的存储库并收集 确定性证据——架构、命名模式、依赖关系， 错误处理——无需调用任何AI模型。然后它递给 向您自己的人工智能助理（Codex、Claude、Junie、Gemini）提供证据， Copilot、Antigravity），它读取您的实际源文件， 解释模式，并生成严格的、特定于项目的 它和其他AI代理将遵循的指令文件 未来运行。

rulesmith方面没有云依赖。无第三方AI呼叫 你无法控制。你的AI，你的订阅，你的数据。

结果：AI的行为就像一个真正阅读的开发人员 代码库——因为它确实如此。

如果你正在开发todo应用程序之外的任何东西，这是 “AI可以写代码”和“AI可以编写代码”之间缺少一层 这符合我们的项目。"

______________________________________________________________________

安全地映射杂乱的代码库。生成有证据支持的代理指令。先呆在当地。

rulesmith 是一个开源 CLI+MCP服务器 对于那些希望在真实世界的存储库中实现高质量AI编码行为的团队。

根据以下许可 阿帕奇-2.0捐款需要签名 贡献者许可协议 在合并之前。

它在三件事上做得很好：

• 收集确定性存储库证据（不产生幻觉）
• 为Codex/Claude/Junie/GGemini-CLI/Antigravity等主机指导可重复的映射工作流程
• 为未来的AI运行生成（或帮助您编写）严格的指令文件

混合发电模型

rulesmith 现在的目标是生成 混合规则手册 默认情况下，当您使用：

• strictness="very-strict"
• standards="project-plus-standard"

混合意味着：

• 存储库特定约定优先
• 只有当兼容的语言/框架标准与存储库的观察模式不矛盾时，它们才会分层
• 当证据确凿时，应保留高信号存储库的特定规则，而不是将其分解为通用指南
• 未解决的冲突或微弱的信号应该继续存在 UNKNOWN/TODO，不可猜

对于默认渲染器，现在存在第一波堆栈感知混合专业化：

• 反应
• Next.js
• 节点/Express
• NestJS
• 快速API
• 姜戈
• Spring Boot
• ASP。NET核心
• 拉瑞维尔
• 飘动
• 安卓
• iOS

确实如此 不 消除第二次AI富集过程的价值。这意味着在富集发生之前，基线现在对回购更加敏感，模板通用性更低。

选择模式

• MCP+主机AI模式（推荐）： 跑 rulesmith 作为Codex/Claude/Junie/Gemini/反重力中的MCP。宿主AI读取证据，并通过推理编写项目特定的规则文件。
• CLI模板模式（辅助/回退）： 跑 rulesmith 从终端(start/render/apply).此模式确实 不 调用任何AI模型；它从scanner+模板中呈现确定性输出。
• 引导模式（新项目）： 当还没有要扫描的代码库时，从用户提供的种子数据（语言/框架/命令）生成规则文件。

如果你的目标是更严格、特定于项目、高质量的规则，那么从MCP+主机AI开始。

现有项目（扫描+证据）

当存储库已经有代码并且您希望从真实文件中获取有证据支持的规则时，请使用此流。

如果你不是技术人员，请将此硬模式提示复制到你的AI编码聊天中。首先替换所有必需的占位符。

Execute this task end-to-end, not as advice.

Repository to install:
https://github.com/CsabaKovacs/rulesmith

Target repository:

Selected instruction targets (comma-separated, choose from: codex,copilot,claude,junie,gemini,antigravity):

Maximum targets per batch (recommended 1-2, default 2):

Strict execution requirements:
- Actually run commands and MCP tools. Do not only describe steps.
- If a command fails, fix it and continue.
- Use absolute paths, except in generated instruction/routing files where paths must be repository-relative (never machine-specific absolute paths).
- Do not stop until scan + generation + apply are complete.
- Use rulesmith MCP tools for repository analysis and rule generation workflow.
- Default generation policy unless explicitly overridden: `strictness="very-strict"` and `standards="project-plus-standard"`.
- Expect the baseline render to be hybrid: repo-first, then compatible standards overlay, then `UNKNOWN/TODO` only for real uncertainty.
- Expect the baseline to retain high-signal repository-specific rules when evidence is strong, especially:
  - flow/reset/redirect patterns
  - typed exception-handling order
  - security ownership boundaries
  - docs or contract sync expectations
  - unusual local risks or legacy oddities
- Do not call `apply_rules` with an empty `files` array.
- If `render_rules` response is too large/truncated, reduce batch size and retry (down to 1 target if needed).
- Do not print full generated file contents to chat; show concise diff summaries and written paths only.
- Keep token usage controlled: prefer `includeContent=false`, scoped evidence reads, and batched target generation.
- If any required input is missing/invalid, ask follow-up questions first and STOP. Do not run commands until inputs are complete.

What to do:

0) Validate required inputs before running anything
- Confirm `` is an absolute path and exists.
- Confirm `` is non-empty and only contains valid values from:
  codex,copilot,claude,junie,gemini,antigravity
- If `` is missing, use 2. Do not exceed 2 unless explicitly requested.
- If any validation fails, ask exactly what is missing, wait for user answer, then continue from step 1.

1) Install or update rulesmith
- If rulesmith is not installed yet, clone the repo to a local absolute path:
  git clone https://github.com/CsabaKovacs/rulesmith.git
- If rulesmith is already installed locally:
  - Check the GitHub repo for a newer version: run `git -C "$RULESMITH_HOME" fetch origin` then compare local HEAD with origin/main.
  - If a newer version is available: `git -C "$RULESMITH_HOME" pull origin main`
  - If no update is needed, skip to step 2.
- Run (first install, or after update):
  - pnpm install
  - pnpm -r build
  - pnpm -r test

2) Register MCP server in this environment
- Set RULESMITH_HOME to the cloned rulesmith path.
- Register rulesmith MCP server using:
  node "$RULESMITH_HOME/packages/mcp/dist/server.js"
- If rulesmith was updated in step 1, restart the MCP server to use the new version.
- Verify MCP registration is active before continuing.

3) Detect layout mode before deep analysis
- run detect_scopes
- if 2+ scopes are detected, ask once whether to use mono or scope mode
- prefer scope mode by default
- in scope mode, run analysis+generation per scope and generate assistant-aware root routing files:
  - codex -> root `AGENTS.md` routing to scoped `*/AGENTS.md`
  - copilot -> root `.github/instructions/*.instructions.md` path-based routing (plus scoped copilot files)
  - claude -> root `CLAUDE.md` routing/imports to scoped `*/CLAUDE.md` (or equivalent scoped rules)
  - gemini -> root `GEMINI.md` routing to scoped `*/GEMINI.md`
  - junie -> root `.junie/guidelines.md` that routes to scope-specific conventions
  - antigravity -> root `.agent/rules/rulesmith.instructions.md` routing to scoped rules
- generated routing/instruction files must use repository-relative paths only (no machine-specific absolute paths)

4) Run full analysis on target repo using MCP
- scan_repo
- build_evidence_bundle with:
  focus="generic", maxFiles=1200, includeContent=false
- Expand evidence with list_files/search/read_files for key areas before finalizing rules.

5) Generate baseline rule files
- Build batches from `` using `` (recommended 1-2 targets per batch).
- For each batch, run render_and_apply with batch targets and policy:
  { strictness: "very-strict", standards: "project-plus-standard" }
  mode: "force"
- This creates template-based baseline rule files with evidence from the scanner.
- The baseline should already reflect hybrid generation behavior:
  - repository-specific architectural and organizational patterns first
  - compatible language/framework standards second
  - preserve high-signal repository-specific rules instead of flattening them into generic advice
  - keep concrete flow, error-handling, security-boundary, and contract-sync conventions when repository evidence is strong
  - avoid generic standards text that contradicts strong repository evidence
- If render_and_apply is not available, fall back to: render_rules → apply_rendered_rules (using artifactId).
- If neither artifact tool is available, fall back to: render_rules(includeContent=true) → apply_rules.

6) AI enrichment pass (MANDATORY — this is where the real value is)
- For EACH scope and EACH generated rule file:
  a) Read the baseline rule file that was just written (e.g., admin/CLAUDE.md).
  b) Read 5-10 key project files to understand actual patterns:
     - 2-3 representative controllers (look for validation, error handling, transaction patterns)
     - 1-2 route files (look for middleware, permission guards, naming conventions)
     - 1-2 model files (look for relationships, scopes, casts)
     - config files relevant to the scope (auth, api, services)
     - package.json / composer.json for dependency context
  c) Based on what you found, REWRITE the rule file to include:
     - Project-specific architectural patterns you observed (not generic template text)
     - Concrete file references as evidence for each convention
     - Specific naming patterns, error handling styles, and code organization rules
     - Any anti-patterns or legacy code that should be explicitly flagged
     - Middleware and permission patterns unique to this scope
  d) PRESERVE these sections exactly as they are in the baseline (do not modify or remove):
     - "Post-Change Review Workflow (MANDATORY)" section — keep every bullet point
     - "Execution Contract" with the BINDING clause
     - "Guardrails" with forbidden paths
     - "UNKNOWN/TODO" section
  e) Write the enriched file using the Edit tool (not apply_rules — you are the author now).
  f) Keep the enriched file under ~15KB to avoid context window issues for future AI sessions.

7) Validate outputs in target repo for selected targets only
Use this mapping:
- codex -> AGENTS.md + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- claude -> CLAUDE.md + .claude/agents/{code-reviewer,security-reviewer,code-simplifier,test-guard}.md
- gemini -> GEMINI.md + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- copilot -> .github/copilot-instructions.md (and optional .github/instructions/*.instructions.md) + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- junie -> .junie/guidelines.md + .junie/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- antigravity -> .agent/rules/rulesmith.instructions.md

8) Final report (required)
Return a concise report with:
- Installed path of rulesmith
- MCP registration status
- Commands executed
- MCP tools executed
- Batch plan used (targets and batch size)
- Files generated/written
- Any warnings or skipped steps

如果您更喜欢手动终端命令，请使用此块：

# If rulesmith is already installed locally, check for updates first:
# git -C /path/to/rulesmith fetch origin && git -C /path/to/rulesmith pull origin main
# If not installed yet, clone it:
git clone https://github.com/CsabaKovacs/rulesmith.git rulesmith
cd rulesmith
pnpm install && pnpm -r build

# Register rulesmith MCP in Codex
codex mcp add rulesmith --env RULESMITH_HOME="$PWD" -- node "$PWD/packages/mcp/dist/server.js"

# Open your target project with Codex
codex -C /absolute/path/to/target-repo

完整的工作流程细节、证据预算和工具参考：

• docs/mcp-workflow.md

主机特定设置指南：

• docs/integrations/README.md

新项目（Bootstrap）

当存储库是新的/空的，并且您希望从所选堆栈中获取初始规则时，请使用此流。

简单的MCP提示（复制/粘贴）：

Use rulesmith MCP to bootstrap a new project (no repository scan).

Repository to install:
https://github.com/CsabaKovacs/rulesmith

Target repository:

Targets:
 (allowed: codex,copilot,claude,junie,gemini,antigravity)

What to do:
1) Install or update rulesmith
- If rulesmith is not installed yet, clone the repo to a local absolute path:
  git clone https://github.com/CsabaKovacs/rulesmith.git
- If rulesmith is already installed locally:
  - Check the GitHub repo for a newer version: run `git -C "$RULESMITH_HOME" fetch origin` then compare local HEAD with origin/main.
  - If a newer version is available: `git -C "$RULESMITH_HOME" pull origin main`
  - If no update is needed, skip to step 2.
- Run (first install, or after update):
  - pnpm install
  - pnpm -r build
  - pnpm -r test
2) Register MCP server in this environment
- Set RULESMITH_HOME to the cloned rulesmith path.
- Register rulesmith MCP server using:
  node "$RULESMITH_HOME/packages/mcp/dist/server.js"
- If rulesmith was updated in step 1, restart the MCP server to use the new version.
- Verify MCP registration is active before continuing.
3) Ask me short questions for language(s), framework(s), package manager/tooling, and install/build/test/lint/format/dev commands.
4) Build a seed object from my answers.
5) Run bootstrap_rules with strictness="very-strict" and standards="project-plus-standard" (baseline generation).
6) Run diff_rules for baseline and summarize shortly.
7) If baseline diff is valid, run apply_rules in safe mode.
8) Run bootstrap_specialization_prompt using the same seed/targets/policy.
9) Use the returned prompt to perform AI specialization pass on the just-generated rule files:
   - enrich with language/framework standards and best practices,
   - add strict quality gates (testing/security/performance/DoD),
   - keep DRY/no-premature-abstraction and file cohesion rules.
10) Show diff for the specialization pass, then apply in safe mode if valid.
11) Validate outputs in target repo for selected targets only:
- codex -> AGENTS.md + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- claude -> CLAUDE.md + .claude/agents/{code-reviewer,security-reviewer,code-simplifier,test-guard}.md
- gemini -> GEMINI.md + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- copilot -> .github/copilot-instructions.md (and optional .github/instructions/*.instructions.md) + .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- junie -> .junie/guidelines.md + .junie/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md
- antigravity -> .agent/rules/rulesmith.instructions.md
12) Return a short final report with:
- rulesmith install path
- MCP registration status
- seed summary (languages/frameworks/commands)
- MCP tools executed
- generated files
- written files
- UNKNOWN/TODO items

为新项目推荐的两步质量流程：

1. bootstrap_rules （来自声明堆栈的基线文件）
2. bootstrap_specialization_prompt （AI二次通过提示）
3. 跑 diff_rules 和 apply_rules 人工智能专业化后

当你还没有现有的代码库时，从种子创建初始规则：

node packages/cli/dist/index.js bootstrap /absolute/path/to/new-repo \
  --languages typescript \
  --frameworks node \
  --targets codex,claude,gemini \
  --install "pnpm install" \
  --test "pnpm -r test" \
  --lint "pnpm -r lint" \
  --mode safe

默认情况下，上述命令还会编写一个AI专门化提示：

• .rulesmith/bootstrap-specialize-prompt.md

将该提示粘贴到您的主机AI聊天中，以严格的语言/框架标准和最佳实践丰富基线规则文件，同时保留回购优先的混合行为。 专业化通行证还应保留高信号存储库的细节，如流重置行为、类型化错误处理顺序、安全所有权边界、文档/合同同步要求，以及存储库证据支持的显著本地风险。

变更后审查工作流程

生成的规则文件包括 变更后审查工作流程 该部分指示宿主AI在完成代码更改后运行自动审查和优化。这为每个生成的规则手册提供了内置的质量、安全性、简化和测试覆盖率检查。

代码修改后，工作流会触发四个专门的代理：

• 代码质量审查 --检查是否遵守规则文件约定、可读性、复杂性和重复性
• 安全审查 --检查OWASP Top 10漏洞、输入验证、身份验证问题和敏感数据暴露（仅当触及安全敏感区域时）
• 代码简化器 --对最近更改的代码进行行为保留清理：减少冗长，整合模式，提高清晰度
• 测试卫士 --评估更改代码的测试覆盖率，识别缺失的测试，并标记回归风险

工作流程顺序已优化：lint→ 审查→ 安全→ 修复关键问题→ 简化→ test → 测试防护装置→ 报告。审查评估开发人员的原始代码，简化程序清理它，测试验证最终状态。

能力自适应生成

审查代理以每个平台的最佳可用格式生成：

所有格式都是从相同的内部生成的 AgentWorkflowSpec --基于检测到的配置文件注入特定于堆栈的规则（语言+框架约定）。

关键设计原则：

• 基于触发器：代理仅在实际代码更改时运行，而不是在琐碎的编辑时运行
• 作用域的安全审查仅在安全相关变更时激活；仅在引入复杂性时才使用简化器
• 行为安全：代码简化器永远不会改变外部行为、公共API或可观察到的副作用
• 非破坏性：审查代理和测试保护报告结果，但不会自动应用修复程序
• 安静：只有在发现问题时才会报告结果（干净代码上没有噪音）
• 堆栈感知：所有代理规则都是针对检测到的语言和框架量身定制的

可以生成什么

对于目标存储库：

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• .junie/guidelines.md
• .agent/rules/rulesmith.instructions.md
• .github/copilot-instructions.md
• 可选的 .github/instructions/*.instructions.md

代理工作流文件（与上述目标一起自动生成）：

• .claude/agents/{code-reviewer,security-reviewer,code-simplifier,test-guard}.md --本机Claude Code子代理（选择Claude目标时）
• .agents/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md --跨平台代理技能（当选择codex、gemini或副驾驶目标时）
• .junie/skills/{code-reviewer,security-reviewer,code-simplifier,test-guard}/SKILL.md --Junie特定技能（当选择Junie目标时）

需求

• Node.js 20+
• pnpm 10+

核心原则

• 本地优先：运行scanner/mapper/renderer不需要云。
• 没有嵌入式LLM调用: rulesmith 不调用任何模型。你的宿主AI会推理。
• 确定性证据：scanner输出置信度和具体文件路径。
• 安全写入：输出仅限于批准的指令路径。
• MCP本地：用作带有主机工具的stdio MCP服务器。

文档

• docs/mcp-workflow.md -MCP工作流程、证据预算和工具详细信息
• docs/cli.md -CLI模式参考
• docs/security-model.md -读/写护栏
• docs/disclaimer.md -完整免责声明
• docs/integrations/README.md -主机设置指南
• docs/references.md -外部参考
• 贡献.md, 安全.md, 总经理, 商标.md, CLA.md

免责声明（简短）

• rulesmith 不是正确性、安全性或合规性保证。
• 您负责审查和验证所有生成的输出。
• MCP+主机AI的使用可能会根据您的主机配置将存储库数据传输到第三方服务。

全文： docs/disclaimer.md