ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs(skills): encourage CLAUDE.md/AGENTS.md reinforcement of critical rules 

Added a "Reinforce Global Rules in Your IDE's Session File" section to
extend-bmad-for-your-org.md. BMad customizations only load when a
skill activates, but IDE session files (CLAUDE.md, AGENTS.md, cursor
rules, copilot-instructions) load every turn — worth restating the
most critical rules there too so they survive ad-hoc chat outside a
BMad skill.

Includes a one-line example reinforcing the Recipe 1 Context7 rule,
plus a scope table that clarifies what each layer is for:
  - IDE session file: universal, every session, keep succinct
  - Agent customization: persona-specific, every dispatched workflow
  - Workflow customization: one workflow run

Emphasizes brevity — noise in the session file crowds out signal.
This commit is contained in:
Brian Madison 2026-04-19 14:15:35 -05:00
parent 89894ef1b7
commit 14ec315e38
1 changed files with 27 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/how-to/extend-bmad-for-your-org.md
View File

@ -134,6 +134,33 @@ brief_template = "{project-root}/docs/enterprise/brief-template.md"
- Use the same structural conventions as the shipped template (section headings, frontmatter) — the agent adapts to what's there
- For multi-org repos, use `.user.toml` to let individual teams point at their own templates without touching the committed team file
## Reinforce Global Rules in Your IDE's Session File
BMad customizations load when a skill is activated. But many IDE tools also load a global instruction file at the **start of every session**, before any skill runs — `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, etc. For rules that should hold even outside BMad skills, restate the critical ones there too.
**When to double up:**
- A rule is important enough that a plain chat conversation (no skill active) should still follow it
- You want belt-and-suspenders enforcement because training-data defaults might otherwise pull the model off-course
- The rule is concise enough to repeat without bloating the session file
**Example — one line in the repo's `CLAUDE.md` reinforcing the dev-agent rule from Recipe 1:**
```markdown
<!-- Any file-read of library docs goes through the context7 MCP tool
(`mcp__context7__resolve_library_id` then `mcp__context7__get_library_docs`)
before relying on training-data knowledge. -->
```
One sentence. Loads every session. Pairs with the `bmad-agent-dev.toml` customization so the rule applies both inside Amelia's workflows and during ad-hoc chats with the assistant. No duplication of effort — each layer owns its scope:
| Layer | Scope | Use for |
|---|---|---|
| IDE session file (`CLAUDE.md` / `AGENTS.md`) | Every session, before any skill activates | Short, universal rules that should survive outside BMad |
| BMad agent customization | Every workflow the agent dispatches | Agent-persona-specific behavior |
| BMad workflow customization | One workflow run | Workflow-specific output shape, publishing hooks, templates |
Keep the IDE file **succinct**. A dozen well-chosen lines are more effective than a sprawling list — models read it every turn, and noise crowds out signal.
## Combining Recipes
All four recipes compose. A realistic enterprise override for `bmad-product-brief` might set `persistent_facts` (Recipe 2), `on_complete` (Recipe 3), and `brief_template` (Recipe 4) in a single file. The agent-level rule (Recipe 1) lives in a separate file under the agent's name and applies in parallel.