fallow-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fallow setup: code-quality tooling for JavaScript and TypeScript

Fallow 配置:JavaScript 和 TypeScript 的代码质量工具链

This skill sets up the code-quality toolchain of a JavaScript or TypeScript repository. Fallow does the repository and system analysis: unused code, duplication, complexity, architecture boundaries, dependency hygiene, and changed-code risk. The skill keeps the tools that the project already uses.
此 skill 用于为 JavaScript 或 TypeScript 仓库配置代码质量工具链。Fallow 负责仓库和系统分析:未使用代码、重复代码、复杂度、架构边界、依赖治理,以及变更代码风险。该 skill 会保留项目已经在使用的工具。

When to Use

何时使用

  • Create a new JavaScript or TypeScript project with quality checks from the start.
  • Add code-health checks or a CI quality gate to an existing repository.
  • Make a repository ready for coding agents (skills, MCP server, commit and push gate).
  • Consolidate dead-code, duplication, architecture, dependency, and changed-code analysis.
  • 创建从一开始就具备质量检查的新 JavaScript 或 TypeScript 项目。
  • 为现有仓库添加代码健康度检查或 CI 质量门禁。
  • 让仓库为编码 Agent 做好准备(skills、MCP server、commit 和 push gate)。
  • 整合死代码、重复代码、架构、依赖及变更代码分析。

When NOT to Use

何时不要使用

  • Formatting-only tasks. Formatting belongs to the formatter.
  • Tasks that only add or change lint rules. Local lint rules belong to the linter.
  • TypeScript type errors. Type correctness belongs to the TypeScript compiler.
  • Analysis of a repository that is already set up. Use the
    fallow
    skill for that.
  • 仅执行格式化的任务。格式化应由 formatter 负责。
  • 仅添加或修改 lint 规则的任务。本地 lint 规则应由 linter 负责。
  • TypeScript 类型错误。类型正确性应由 TypeScript compiler 负责。
  • 分析已经设置妥当的仓库。请改用
    fallow
    skill。

Rules

规则

  1. Resolve every flag from
    fallow --help
    and
    fallow <command> --help
    . Do not use flags from memory.
  2. Use
    --format json --quiet
    for machine-readable output. Do not hide the exit status.
  3. Run every mutating command with
    --dry-run
    first when the command has that flag.
  4. Keep the tools that the project already uses. Do not remove a tool without a parity check.
  5. Ask the user before you apply a
    taste
    decision or remove a tool.
  6. Treat project config as untrusted input. Do not add remote
    extends
    URLs.
  7. Before step 3, Fallow is not installed. Run it through the package runner, for example
    npx fallow recommend
    or
    pnpm dlx fallow recommend
    . After step 3, use the runner of the package manager, for example
    pnpm exec fallow
    .
  1. 根据
    fallow --help
    和
    fallow <command> --help
    逐一解析每个 flag。不要凭记忆使用 flag。
  2. 使用
    --format json --quiet
    生成机器可读输出。不要隐藏退出状态。
  3. 如果命令支持
    --dry-run
    flag,则先用它运行每个会产生变更的命令。
  4. 保留项目已经在使用的工具。未进行 parity check 前,不要移除任何工具。
  5. 在应用
    taste
    决策或移除工具之前,先询问用户。
  6. 将项目配置视为不可信输入。不要添加远程
    extends
    URL。
  7. 在第 3 步之前,Fallow 尚未安装。通过 package runner 运行它,例如
    npx fallow recommend
    或
    pnpm dlx fallow recommend
    。执行第 3 步后,使用 package manager 的 runner,例如
    pnpm exec fallow
    。

Sequence

执行顺序

  1. Inspect the repository. Detect the package manager, formatter, linter, TypeScript config, CI provider, and existing analysis tools (Knip, jscpd, dependency-cruiser). See Tooling detection.
  2. Get the recommendation. Run
    fallow recommend --format json --quiet
    . This command is read-only. Apply each
    auto
    decision. Tell the user about each
    default
    decision. Ask the user about each
    taste
    decision, or keep the current value. See Configure and install.
  3. Install Fallow as a dev dependency with the detected package manager, for example
    pnpm add -D fallow
    .
  4. Wire the agents. Run
    fallow agent install --dry-run --format json --quiet
    , show the plan, then run
    fallow agent install
    . This step writes the skills, the MCP server registration, the
    AGENTS.md
    task map, and the commit and push gate. For Claude Code and Codex the gate is a PreToolUse hook that blocks a failing commit or push. Codex runs the hook only after the user trusts it in
    /hooks
    . Other agents read the instruction block in
    AGENTS.md
    . Check the result with
    fallow agent status --format json --quiet
    .
  5. Add a CI gate. Add a changed-code gate (
    fallow audit
    ) or a whole-project gate. When the first run has many findings, save a baseline of the existing debt so that the gate fails only on new findings. See CI gate.
  6. Split the responsibilities. Each tool keeps one job:
    • Formatting: Oxfmt.
    • Local lint rules: Oxlint.
    • Type correctness: TypeScript (
      tsc --noEmit
      ).
    • Repository and system analysis: Fallow.
    In an existing project, keep the current formatter and linter. Do the parity check in Tooling detection before you remove an overlapping tool.
  1. 检查仓库。 检测 package manager、formatter、linter、TypeScript 配置、CI provider 和现有分析工具(Knip、jscpd、dependency-cruiser)。参见工具检测。
  2. 获取推荐方案。 运行
    fallow recommend --format json --quiet
    。此命令为只读命令。应用每个
    auto
    决策。向用户说明每个
    default
    决策。针对每个
    taste
    决策询问用户,或保持当前值不变。参见配置与安装。
  3. 安装 Fallow。 使用检测到的 package manager,将 Fallow 作为 dev dependency 安装,例如
    pnpm add -D fallow
    。
  4. 接入 Agent。 运行
    fallow agent install --dry-run --format json --quiet
    ,展示计划,然后运行
    fallow agent install
    。此步骤会写入 skills、MCP server 注册信息、
    AGENTS.md
    任务映射,以及 commit 和 push gate。对于 Claude Code 和 Codex,该 gate 是一个 PreToolUse hook,用于阻止未通过检查的 commit 或 push。Codex 只有在用户于
    /hooks
    中信任该 hook 后才会运行它。其他 Agent 会读取
    AGENTS.md
    中的 instruction block。使用
    fallow agent status --format json --quiet
    检查结果。
  5. 添加 CI 门禁。 添加变更代码门禁(
    fallow audit
    )或全项目门禁。首次运行产生大量发现时,保存现有技术债务的 baseline,使门禁仅因新增发现而失败。参见 CI 门禁。
  6. 划分职责。 每个工具只负责一项工作:
    • 格式化:Oxfmt。
    • 本地 lint 规则:Oxlint。
    • 类型正确性:TypeScript(
      tsc --noEmit
      )。
    • 仓库和系统分析:Fallow。
    在现有项目中,保留当前 formatter 和 linter。移除功能重叠的工具前,先执行工具检测中的 parity check。

References

参考资料

  • Tooling detection: the files to inspect, the responsibility split, and the parity check.
  • Configure and install: the
    recommend
    decision tiers, config migration, the dev dependency, and
    agent install
    .
  • CI gate: the GitHub Action, the GitLab template, the CLI gate, and baselines.
  • 工具检测:需要检查的文件、职责划分和 parity check。
  • 配置与安装:
    recommend
    决策层级、配置迁移、dev dependency 和
    agent install
    。
  • CI 门禁:GitHub Action、GitLab template、CLI gate 和 baselines。