From d2cc428499f923c9329e886e601aa83700e7a4c0 Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 16 Jan 2026 21:03:31 +0000
Subject: [PATCH 1/2] docs(rules): add nix-workflow rule for development and CI
 guidance

- Add .claude/rules/nix-workflow.md with guidance on:
  - Using flake.nix with flake-parts for dev environment
  - Adding tools to buildInputs
  - Treefmt and git-hooks configuration
  - CI workflow with setup-nix action
  - Recommended build flags (--print-build-logs --show-trace)
- Update CLAUDE.md to include nix-workflow in available rules table

Based on stackone-ai-node's nix-workflow.md, adapted for Python SDK
with flake-parts, treefmt-nix, and git-hooks.nix specifics.
---
 .claude/rules/nix-workflow.md | 99 +++++++++++++++++++++++++++++++++++
 CLAUDE.md                     |  1 +
 2 files changed, 100 insertions(+)
 create mode 100644 .claude/rules/nix-workflow.md

diff --git a/.claude/rules/nix-workflow.md b/.claude/rules/nix-workflow.md
new file mode 100644
index 0000000..6e4e04e
--- /dev/null
+++ b/.claude/rules/nix-workflow.md
@@ -0,0 +1,99 @@
+# Nix Workflow
+
+This rule provides guidance on Nix usage in the StackOne AI Python SDK.
+
+## Development Environment
+
+The project uses `flake.nix` with flake-parts to define the development environment. Enter it with `nix develop`.
+
+### Adding Development Tools
+
+To add a new tool to the development environment, add it to `buildInputs` in `flake.nix`:
+
+```nix
+devShells.default = pkgs.mkShellNoCC {
+  buildInputs = with pkgs; [
+    uv
+    ty
+    just
+    nixfmt-rfc-style
+
+    # your new tool here
+    new-tool
+  ];
+};
+```
+
+### Treefmt and Git Hooks
+
+The flake includes:
+
+- **treefmt-nix**: Unified formatting (nixfmt, ruff, oxfmt)
+- **git-hooks.nix**: Pre-commit hooks (gitleaks, treefmt, ty)
+
+These are automatically installed when entering the dev shell.
+
+## CI Workflow
+
+CI uses `nix profile install` via the `.github/actions/setup-nix/action.yaml` composite action.
+
+### Adding Tools to CI Jobs
+
+Specify tools in the `tools` input of the setup-nix action:
+
+```yaml
+- name: Setup Nix
+  uses: ./.github/actions/setup-nix
+  with:
+    tools: uv ty just bun pnpm_10
+```
+
+The action installs packages using:
+
+```bash
+nix profile install --inputs-from . nixpkgs#tool1 nixpkgs#tool2
+```
+
+### CI Tool Configuration
+
+- **Default tools**: `uv ty just` (defined in action.yaml)
+- **Skip uv sync**: Set `skip-uv-sync: 'true'` for jobs that don't need Python dependencies
+
+### Example: Adding a New Tool to CI Job
+
+```yaml
+ci:
+  runs-on: ubuntu-latest
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+    - name: Setup Nix
+      uses: ./.github/actions/setup-nix
+      with:
+        tools: uv ty just new-tool
+    - name: Run Lint
+      run: just lint
+```
+
+## Build Flags
+
+Always use these flags when running Nix build commands locally:
+
+```bash
+--print-build-logs --show-trace
+```
+
+Example:
+
+```bash
+nix build --print-build-logs --show-trace
+nix flake check --print-build-logs --show-trace
+```
+
+## Notes
+
+- The project uses flake-parts for modular flake configuration
+- Git submodules are initialised automatically in dev shell and CI
+- MCP mock server dependencies (pnpm) are installed for testing
diff --git a/CLAUDE.md b/CLAUDE.md
index f956908..7d3a72c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | **git-workflow**             | All files           | Commit conventions, branch strategy, PR guidelines |
 | **development-workflow**     | All files           | Code style, file naming, project conventions       |
 | **release-please-standards** | All files           | Release versioning with release-please             |
+| **nix-workflow**             | All files           | Nix development environment and CI configuration   |
 | **no-relative-imports**      | `**/*.py`           | Enforce absolute imports in Python files           |
 | **package-installation**     | `**/pyproject.toml` | UV package management standards                    |
 | **uv-scripts**               | `scripts/**/*.py`   | Utility script standards with UV                   |

From a7762af8331da538578793594eb093ebd827ea11 Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 16 Jan 2026 21:07:40 +0000
Subject: [PATCH 2/2] docs(rules): remove build flags section from nix-workflow

These flags are only needed for debugging and slow down normal builds.
---
 .claude/rules/nix-workflow.md | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/.claude/rules/nix-workflow.md b/.claude/rules/nix-workflow.md
index 6e4e04e..c9234ac 100644
--- a/.claude/rules/nix-workflow.md
+++ b/.claude/rules/nix-workflow.md
@@ -77,21 +77,6 @@ ci:
       run: just lint
 ```
 
-## Build Flags
-
-Always use these flags when running Nix build commands locally:
-
-```bash
---print-build-logs --show-trace
-```
-
-Example:
-
-```bash
-nix build --print-build-logs --show-trace
-nix flake check --print-build-logs --show-trace
-```
-
 ## Notes
 
 - The project uses flake-parts for modular flake configuration