98 lines
3 KiB
Markdown
98 lines
3 KiB
Markdown
---
|
|
title: AI Assistance Guide
|
|
modified: 2026-03-03
|
|
tags:
|
|
- tutorials
|
|
- ai
|
|
---
|
|
|
|
# AI Assistance Guide
|
|
|
|
> **Audiences:** AI, Owner
|
|
|
|
This guide provides context for AI agents (like Claude Code) assisting with this project.
|
|
|
|
## Critical Rules
|
|
|
|
These are non-negotiable for AI agents working in this repo:
|
|
|
|
1. **Run `mise run ai-docs` at session start** — Review project documentation
|
|
2. **Never commit secrets** — The repo may be public
|
|
3. **Wait for user review before deploying** — Create PRs, don't auto-deploy
|
|
4. **Never merge PRs without explicit request** — The user merges after review
|
|
|
|
Full rules are in the repo's `CLAUDE.md`. See [[agent-change-process]] for the C0/C1/C2 change classification methodology — C0 (direct to main), C1 (feature branch + PR), C2 (Mikado Branch Invariant).
|
|
|
|
## Workflow Conventions
|
|
|
|
### Branching
|
|
|
|
Branching depends on change classification (see [[agent-change-process]]):
|
|
|
|
- **C0 (Quick Fix):** Commit directly to main — no branch or PR needed
|
|
- **C1/C2:** Feature branch required:
|
|
```bash
|
|
git checkout main && git pull
|
|
git checkout -b feature/descriptive-name
|
|
# ... make changes ...
|
|
git commit -m "Description"
|
|
```
|
|
|
|
### Pull Requests
|
|
|
|
Use the forge's `tea` CLI:
|
|
```bash
|
|
tea pr create --title "Title" --description "$(cat <<'EOF'
|
|
## Summary
|
|
- Change 1
|
|
- Change 2
|
|
|
|
## Testing
|
|
- [ ] Test step
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### Changelog Fragments
|
|
|
|
Add a fragment for user-visible changes:
|
|
```bash
|
|
# C1/C2: use branch name
|
|
echo "Description" > docs/changelog.d/branch-name.feature.md
|
|
|
|
# C0: use orphan prefix (no branch to name after)
|
|
echo "Description" > docs/changelog.d/+descriptive-slug.feature.md
|
|
```
|
|
|
|
Types (file suffix): `.feature`, `.bugfix`, `.infra`, `.doc`, `.ai`, `.misc`
|
|
|
|
### Wiki-Link Formatting
|
|
|
|
Use simple wiki-links without alternate text or extra spaces:
|
|
- Prefer `[[borgmatic]]` over `[[borgmatic|Borgmatic]]`
|
|
- Only use alternate text when grammatically warranted
|
|
- No spaces around the pipe: `[[path|Text]]` not `[[ path|Text ]]`
|
|
|
|
When editing documentation, rewrite links to follow this convention as you encounter them.
|
|
|
|
## Mise Tasks
|
|
|
|
Run `mise tasks` to list all available tasks.
|
|
|
|
| Task | When to Use |
|
|
|------|-------------|
|
|
| `ai-docs` | At session start — review project documentation |
|
|
| `docs-mikado` | View active Mikado dependency chains for C2 changes |
|
|
| `docs-mikado --resume` | Resume a C2 chain: detect branch, show state and next steps |
|
|
| `pr-comments` | Check unresolved PR comments during review |
|
|
| `docs-check-links` | Validate wiki-links in documentation (includes orphan detection) |
|
|
| `docs-check-index` | Check every doc is referenced in its category index |
|
|
| `docs-check-filenames` | Check for duplicate doc filenames |
|
|
|
|
## Common Pitfalls
|
|
|
|
| Pitfall | Correct Approach |
|
|
|---------|------------------|
|
|
| Deploying without review | Create PR first, wait for user approval |
|
|
| Re-explaining reference material | Link to reference cards instead |
|
|
| Committing to main without classifying | Classify as C0/C1/C2 first — only C0 goes to main |
|