chore: update AI tooling docs/settings - #422
Merged
Merged
Conversation
The repo told Claude Code to prefer the flow MCP tools while making Bash the cheaper path: .mcp.json was untracked so a fresh clone had no flow server at all, CLAUDE.md led with shell commands and duplicated a staler copy of the flow-context skill, and the four task skills restricted allowed-tools to Bash(flow ...) with no mcp__flow__* entries at all. - commit .mcp.json so every clone gets the server - make CLAUDE.md defer to flow-context as the single source of truth and present executables by ref rather than as shell invocations - add mcp__flow__* to each skill's allowed-tools, and fix the frontmatter to the documented comma-separated form (was space-separated, and pr-ready used Bash(git *) instead of Bash(git:*)) - correct stale paths: handlers are in cmd/internal/, runner types are subpackages, schemas are types/executable/*_schema.yaml -> *.gen.go Also documents committing .mcp.json in the AI Tools guide, which is the step that turns one user's setup into a team's. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Critical Rule #1 ("never edit generated files") and the no-push convention were instructions the model could simply not follow. Move them into permission rules, which deny takes precedence over and no local setting can override. - deny writes to types/**/*.gen.go and the generated docs trees - deny secret-leaking reads: flow secret get/list, env dumps, .env files - ask on push, force-reset, gh pr/issue/release, publish, docker push - document tuikit and vault as the two first-party modules that carry most behavior, and the version-skew trap: no replace directives, so a sibling working copy is often at a different version than the build - state the scope boundary explicitly — flow provides AI tools via MCP and does not consume an LLM in the CLI Machine-specific paths (additionalDirectories for the module cache and sibling checkouts) stay in the gitignored settings.local.json so the committed file remains portable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md is the only file loaded in full every session, so it was the one place worth optimizing. Skill bodies load on invocation, not at startup, so their length is nearly free. Critical Rule #1 claimed all of types/**/*.go was generated. Only the three *.gen.go files are; eight hand-written files sit alongside them, so the rule told the model not to edit code it should edit. - fix rule #1 to name *.gen.go, and point at the real schema sources - merge Common Pitfalls into Critical Rules; they overlapped ~60% - fold the Code Generation section into rule #1, now that permission rules enforce it rather than prose - drop Key Technologies (version is in setup; the rest is evident from imports) and collapse the package tree annotations - correct the claim that the flow-context skill auto-loads each session Net 13% smaller than before the sibling-repo and scope sections were added, 42% below peak. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.