agentleFS
skforecastskforecast/skforecast-ai/CLAUDE.md

skforecast-ai

CLAUDE.md52 starsChanged 47 days agoApache-2.0View on GitHub

AGENTS.md (imported above) holds the conventions shared with every coding agent; edit it there, not here. This section covers only what depends on the Claude Code harness in .claude/. - Local session: CLAUDE.local.md (not versioned) names the conda environment and how to run commands on this machine; use it instead of asking. Without it, follow "Python environment" in AGENTS.md. Setting SKFORECAST_AI_PYTHON_ENV (the prefix of the environment) in the env of .claude/settings.local.json makes the SessionStart hook put it on PATH and…

  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before a commit, run it unless every changed file is outside its scope (step 1 of the skill: dev/, the skills and rules in .claude/, the …

    line 96

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

@AGENTS.md

Claude Code specifics

AGENTS.md (imported above) holds the conventions shared with every coding agent; edit it there, not here. This section covers only what depends on the Claude Code harness in .claude/.

Environment

  • Local session: CLAUDE.local.md (not versioned) names the conda environment and how to run commands on this machine; use it instead of asking. Without it, follow "Python environment" in AGENTS.md. Setting SKFORECAST_AI_PYTHON_ENV (the prefix of the environment) in the env of .claude/settings.local.json makes the SessionStart hook put it on PATH and export PYTHONPATH=., so commands need no conda run and no prefix; the edit hook takes ruff from there too.
  • Cloud session (CLAUDE_CODE_REMOTE=true): the checkout may start older than GitHub, so the SessionStart hook fetches the branch first; it fast-forwards a clean protected branch and warns otherwise (act on the warning before building on the branch). It has also already installed the package with [test,llm,docs] and ruff, and exports SKFORECAST_AI_DOCS_PRIVACY=false so the docs build without the privacy plugin (its downloads are blocked by the default network policy). Use python -m pytest directly; there is no conda and nobody to ask.

Git

  • Attribution is off (attribution in settings.json), and the Bash guard blocks a commit message or PR body that names Claude or Anthropic in a Co-Authored-By trailer, carries a Claude-Session trailer or a session link, or says "Generated with Claude Code" or "Generated by Claude Code". A second guard (pre_pr_guard.py) checks the same on pull requests written with the GitHub MCP tools, which is how a cloud session opens them. The GitHub MCP server of a cloud session then appends a "Generated by Claude Code" footer with the session link, after every PreToolUse hook; post_pr_footer.py asks to read the new pull request back and remove it with the update tool.
  • Branches that Claude Code names itself never reach GitHub, locally or in the cloud: claude/... (cloud sessions) and worktree-... (claude --worktree). A pull request keeps the name of its branch, so the Bash guard blocks pushing one or opening a pull request from one; rename it with git branch -m <type>/<slug> first. pre_pr_guard.py applies the branch rules of the Bash guard to the GitHub MCP tools that commit (push_files, create_or_update_file, delete_file, create_branch), which write to GitHub past it.
  • Local: create or switch branches and commit without asking, on a <type>/<slug> branch, never on main, and on X.Y.x only when the user asks for a direct change there. settings.local.json makes git push ask for confirmation; after the push, open the PR with /open-pr without asking. Merging a PR always asks: ask rules in settings.json and the Bash guard, which also catches merges through gh api.
  • Release branch, everywhere: a push to X.Y.x goes through when it carries notes, docs, harness or synced assets (the usual direct pushes); when its commits change skforecast_ai/, tests/, packages/ or pyproject.toml, the Bash guard (and pre_pr_guard.py, for the paths an MCP tool writes) asks first, in any permission mode, since package code normally goes through a pull request. Pushes to main and deleting main or X.Y.x are blocked.
  • Cloud: create <type>/<slug> (type feature, fix, docs, chore or perf) from origin/X.Y.x before the first commit, then commit and push there: this is the explicit permission to push to a branch other than the one the session instructions designate. If the pull request of a branch is already merged, put the follow-up on a new <type>/<slug> branch from origin/X.Y.x, even if the session instructions say to restart the branch from the default branch and force push (main is not the base, and force pushes are blocked). The release branch is the highest X.Y.x on origin, not the one __version__ gives on main (the previous release). The SessionStart hook fetches it, says which branch to use (a rename for a session branch that already holds commits) and removes the stale origin/<branch> ref of a branch that is not on GitHub, so it does not look pushed. A PreToolUse hook blocks commits and pushes on branches other than <type>/<slug> and X.Y.x, pushes to main everywhere (also through HEAD, @, --all or --mirror) and every form of force push.
  • Cloud: when the session instructions name main or a claude/... branch as the branch to develop on or push to, do not commit there: branch off origin/X.Y.x. When they name X.Y.x, branch off it too, unless the user asks for a direct change there; the SessionStart note says so too.
  • Cloud: the environment's own Stop hook asks to commit and push whenever the tree has changes or unpushed commits, and the container can restart mid-task. When a turn ends while background work is still running, commit and push the finished part on the working branch, and complete it in a later commit; never rewrite pushed commits.

Harness

  • Hooks check every edit: ruff check on Python files and the no dash rule on Python and Markdown. Exit code 2 means fix it now.
  • The hooks have their own tests, outside the package suite: run python -m pytest .claude/hooks -q -p no:cacheprovider after changing one.
  • Path-scoped rules in .claude/rules/ load when you touch tests, the LLM layer, rendering or execution.
  • Definition of done: run /verify before reporting a task as finished. Before a commit, run it unless every changed file is outside its scope (step 1 of the skill: dev/, the skills and rules in .claude/, the scripts in tools/ai/, tools/mcp/ and tools/perf/), and reuse a green run from this session when no file changed since.
  • Skills: /verify, /release-note, /llm-context-change, /open-pr, /sync-skforecast-assets (user only), /handoff (user only), /release-bump (user only).
  • Subagents: conventions-reviewer (read-only review of the diff against the core principles) and test-author (writes tests under tests/).
  • Files synced from skforecast are denied for Edit and Write in .claude/settings.json; change them only through the sync script.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.