Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c5e6ebb534 | ||
|
|
94eb7ef70a | ||
|
|
dfa84743f9 | ||
|
|
154f592f3c |
No files matched your search
@@ -0,0 +1,795 @@
|
||||
# AGENTS.md — team-guide
|
||||
|
||||
Working agreements for our 1–3 person AI-assisted development team.
|
||||
This is the canonical spec for AI coding agents (Claude Code, Codex,
|
||||
and any other `AGENTS.md`-aware tool). Claude Code reads this via
|
||||
`CLAUDE.md`'s `@AGENTS.md` import, so there's exactly one source of
|
||||
truth.
|
||||
|
||||
> Human-facing entry point: [`README.md`](README.md) (Chinese,
|
||||
> condensed). When humans want the full ruleset, they read this file.
|
||||
|
||||
## How AI agents use this repo
|
||||
|
||||
Before starting non-trivial work in any team project, an agent should:
|
||||
|
||||
1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
|
||||
style, planning, handoff).
|
||||
2. **Scan [`library/README.md`](library/README.md)** — focused specs
|
||||
for narrower topics. Read the entries that match the current task.
|
||||
3. **Read the project's own `AGENTS.md`** — project-specific stuff
|
||||
(how to run it, architecture, project-only don'ts). Project AGENTS.md
|
||||
files do **not** repeat team-guide content; they reference it.
|
||||
|
||||
In short: team-guide is the external rulebook every project's agent
|
||||
reads at task start. Project AGENTS.md files stay small and specific.
|
||||
|
||||
## Project
|
||||
|
||||
This repo holds our team's working agreements. It is **documentation,
|
||||
not code** — no build, test, or lint step. Acceptance is "a human can
|
||||
read the change and would have written the same."
|
||||
|
||||
## Editing rules (this repo)
|
||||
|
||||
- One rule per bullet. If a rule needs a paragraph of justification,
|
||||
split the rule out and put the reason on a `**Why:**` line.
|
||||
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only
|
||||
when the rule isn't self-evident.
|
||||
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
|
||||
- Keep AGENTS.md under ~800 lines. Past that, split.
|
||||
- Examples beat prose. A 3-line code block beats a paragraph.
|
||||
|
||||
## Language policy
|
||||
|
||||
- **Human-facing**: Chinese — `README.md` only.
|
||||
- **AI-facing**: English — this file, `CLAUDE.md`, anything under
|
||||
`library/`.
|
||||
- **Git metadata**: English — commit messages, PR titles, branch
|
||||
names, tag annotations. AI tools and search work better on English.
|
||||
|
||||
If you're an agent about to write Chinese into a file the human would
|
||||
never read (or English into a file only humans read), stop — wrong file.
|
||||
|
||||
## CLAUDE.md and AGENTS.md sync
|
||||
|
||||
Claude Code reads `CLAUDE.md`; Codex and other agents read `AGENTS.md`.
|
||||
In this repo, `CLAUDE.md` is a single line: `@AGENTS.md`. That makes
|
||||
this file the only spec; both tools see the same content.
|
||||
|
||||
For other projects in our workspace where the two files are physical
|
||||
copies (legacy or tool-mismatch reasons), the rules are:
|
||||
|
||||
- Bodies must stay in sync. Drift breaks one of the tools silently.
|
||||
- Whoever edits one updates the other in the same PR. Add "Synced
|
||||
AGENTS.md" (or "Synced CLAUDE.md") to the PR description.
|
||||
- Reviewer blocks PRs that only touch one side.
|
||||
|
||||
When starting a new project, prefer the single-file approach: write
|
||||
`AGENTS.md`, make `CLAUDE.md` a one-line `@AGENTS.md` import.
|
||||
|
||||
---
|
||||
|
||||
## 1. Vibe coding — humans + AI work split
|
||||
|
||||
### The premise
|
||||
|
||||
Claude / Codex write most of the code. Humans steer: framing problems,
|
||||
making decisions, deciding what's good enough. We're not racing the AI
|
||||
— we're skipping typing so we spend more time thinking.
|
||||
|
||||
### The split
|
||||
|
||||
**AI does:**
|
||||
|
||||
- Read code and explain it
|
||||
- Write first-pass implementations against a clear spec
|
||||
- Mechanical refactors (renames, extractions, type changes)
|
||||
- Run tests, builds, linters; iterate on errors
|
||||
- Generate boilerplate (configs, fixtures, CRUD)
|
||||
- Search across the workspace and summarize
|
||||
|
||||
**Humans do:**
|
||||
|
||||
- Decide what to build and why
|
||||
- Frame the spec before AI touches code
|
||||
- Approve any change with non-local consequences (deps, schema, infra,
|
||||
auth, secrets)
|
||||
- Read every diff before merging
|
||||
- Make the call when AI has tried twice and is going in circles
|
||||
- Sign off on commit messages and PR descriptions (AI drafts; you sign)
|
||||
|
||||
If a task feels like it's drifting toward "AI decides", stop and write
|
||||
a spec yourself first.
|
||||
|
||||
### Prompt habits
|
||||
|
||||
- **Frame, don't dictate.** Tell AI the goal, the constraints, and what
|
||||
you've ruled out. Don't prescribe steps unless the steps are the point.
|
||||
- **Name the file.** "Fix the bug in `eval-agent/runner.py`" beats "fix
|
||||
the bug." Save AI a search.
|
||||
- **Say what done looks like.** "Tests pass and the new flag defaults
|
||||
to off" — measurable. "Make it cleaner" — not.
|
||||
- **One task per turn.** Three unrelated asks → three messages or three
|
||||
sessions.
|
||||
- **Push back on bad output.** If the diff is wrong, say so plainly and
|
||||
point at what's wrong. Don't accept code you wouldn't write yourself.
|
||||
|
||||
### When to take over
|
||||
|
||||
Stop letting AI drive when:
|
||||
|
||||
- It's failed the same approach twice and the error is unchanged.
|
||||
- It's adding "safety" code the task didn't ask for.
|
||||
- The diff has grown past what you can read in one sitting.
|
||||
- You can't explain the change to a teammate without re-reading the diff.
|
||||
- It's about to do something irreversible — confirm explicitly.
|
||||
|
||||
When you take over, write *why* in the PR description so the next person
|
||||
doesn't repeat the loop.
|
||||
|
||||
### Verifying AI output
|
||||
|
||||
Treat every AI diff like a fast junior's PR:
|
||||
|
||||
1. Does it build?
|
||||
2. Do tests pass — and do new tests actually test the new code?
|
||||
3. Did it touch files outside the stated scope? Look at every one.
|
||||
4. Did it add deps? Check the lockfile diff.
|
||||
5. Read every comment AI added. Half are noise — delete those.
|
||||
6. Run user-facing features end-to-end. Type checks ≠ working software.
|
||||
|
||||
### Anti-patterns
|
||||
|
||||
- **Snowballing context.** Long sessions accumulate stale assumptions.
|
||||
New task → new session.
|
||||
- **Approval-by-default.** "Looks good" without reading the diff is how
|
||||
bugs ship.
|
||||
- **Outsourcing the spec.** "Figure out what we should do" is avoidance,
|
||||
not a prompt.
|
||||
- **Letting AI rewrite history.** If AI wants to refactor unrelated code
|
||||
"while we're here", say no. Open a separate task.
|
||||
|
||||
---
|
||||
|
||||
## 2. Claude Code & Codex configuration
|
||||
|
||||
### Per-project files
|
||||
|
||||
```
|
||||
<repo>/
|
||||
├── AGENTS.md ← canonical spec, committed
|
||||
├── CLAUDE.md ← committed, single line: @AGENTS.md
|
||||
└── .claude/
|
||||
├── settings.json ← shared settings, committed
|
||||
├── settings.local.json ← personal overrides, gitignored
|
||||
└── skills/ ← project skills, committed
|
||||
```
|
||||
|
||||
`settings.local.json` is **always** gitignored — personal API keys,
|
||||
local paths, individual hook tweaks.
|
||||
|
||||
### AGENTS.md content per project
|
||||
|
||||
In this order:
|
||||
|
||||
1. **Project** — two sentences max.
|
||||
2. **Run it** — build, test, lint as bash blocks.
|
||||
3. **Architecture** — one paragraph. Entry points and data flow. No
|
||||
diagrams unless they save words.
|
||||
4. **Conventions specific to this repo** — naming, layout, patterns
|
||||
that aren't obvious from the code.
|
||||
5. **Don'ts** — things AI has gotten wrong before. One line each.
|
||||
|
||||
A new contributor (human or AI) should be productive after one read.
|
||||
Past 100 lines, split — it's drifted into "documentation."
|
||||
|
||||
Skeleton to copy into a new project's `AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
# AGENTS.md — <project name>
|
||||
|
||||
> Reference: team-guide (https://git.simgreek.com/simgreek/team-guide)
|
||||
> for cross-project rules. This file holds only what's specific to
|
||||
> this project.
|
||||
|
||||
## Project
|
||||
|
||||
<one or two sentences>
|
||||
|
||||
## Run it
|
||||
|
||||
```bash
|
||||
<install / run / test / lint commands>
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
<one paragraph: entry points, data flow, major modules>
|
||||
|
||||
Key files:
|
||||
- `<path>` — <one-line role>
|
||||
|
||||
## Conventions specific to this repo
|
||||
|
||||
<naming patterns, where to add new features, what's auto-generated>
|
||||
|
||||
## Don'ts
|
||||
|
||||
- Don't <…>
|
||||
```
|
||||
|
||||
`CLAUDE.md` in a new project is one line: `@AGENTS.md`.
|
||||
|
||||
### Permissions (Claude Code)
|
||||
|
||||
Default: prompt for risky, allow read-only freely.
|
||||
|
||||
In `.claude/settings.json`, allow without prompting:
|
||||
|
||||
- All `Read`, `Glob`, `Grep`
|
||||
- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`,
|
||||
`Bash(git branch)`
|
||||
- Project-specific read-only commands (`Bash(npm test)`, `Bash(pytest)`)
|
||||
|
||||
Always prompt for:
|
||||
|
||||
- `Edit` / `Write` outside the working tree
|
||||
- `Bash` with destructive verbs (`rm`, `mv`, `git push`,
|
||||
`git reset --hard`, package installs)
|
||||
- Any MCP tool that talks to a remote service
|
||||
|
||||
Approving the same prompt repeatedly → run the
|
||||
`fewer-permission-prompts` skill to propose an allowlist from your
|
||||
transcripts.
|
||||
|
||||
### Codex approval & sandbox
|
||||
|
||||
- **Approval**: default `on-request` (asks before commands). Use
|
||||
`on-failure` or `never` only on personal, low-risk machines.
|
||||
Production / shared / unfamiliar repos → keep `on-request`.
|
||||
- **Sandbox**: default `workspace-write` + network off. Toggle network
|
||||
on temporarily to install packages or fetch resources, then off.
|
||||
`danger-full-access` rarely.
|
||||
- Personal Codex preferences in `~/.codex/config.toml` — never commit.
|
||||
|
||||
### Hooks
|
||||
|
||||
Hooks enforce rules automatically. AI **does not reliably remember**
|
||||
"from now on do X" across sessions; hooks do.
|
||||
|
||||
Use hooks for:
|
||||
|
||||
- Auto-formatting on file edit (Prettier, ruff, gofmt)
|
||||
- Blocking edits to protected paths (`.env`, generated files, `dist/`)
|
||||
- Auto-running tests after writing to a known test path
|
||||
- Notifying on session stop / long-task completion
|
||||
|
||||
Don't use hooks for:
|
||||
|
||||
- One-off checks ("just remember X this week")
|
||||
- Anything that depends on AI judgment
|
||||
|
||||
Configure via `update-config` skill or edit `.claude/settings.json`
|
||||
directly. One-line comment per hook.
|
||||
|
||||
### Memory
|
||||
|
||||
Per-machine memory system. Use it for:
|
||||
|
||||
- **User**: who you are, role, preferences.
|
||||
- **Feedback**: corrections that should stick across sessions, with
|
||||
the *why*.
|
||||
- **Project**: facts about ongoing work that aren't in the code
|
||||
(deadlines, stakeholder decisions, why a refactor is happening).
|
||||
- **Reference**: pointers to external resources (Linear, Grafana,
|
||||
internal wikis).
|
||||
|
||||
Don't put memory content in `AGENTS.md`. AGENTS.md is shared with the
|
||||
team; memory is personal, per-machine, outside the repo. Don't use
|
||||
memory as a notes app — task-scoped state goes in plans or PR descriptions.
|
||||
|
||||
### Skills
|
||||
|
||||
Skills live in three places:
|
||||
|
||||
- **User skills** (`~/.claude/skills/`) — installed once, available
|
||||
everywhere
|
||||
- **Project skills** (`<repo>/.claude/skills/`) — committed, team-shared
|
||||
- **Plugin skills** — installed via marketplace
|
||||
|
||||
Promote a workflow to a skill when **all three** are true:
|
||||
|
||||
1. Done it the same way three times.
|
||||
2. Steps stable enough to write down.
|
||||
3. Someone else would do it the same way given the spec.
|
||||
|
||||
Only two true → leave it as a prompt snippet.
|
||||
|
||||
Skill design:
|
||||
|
||||
- One skill, one job. Branching skills are two skills.
|
||||
- Verb-phrase names: `review-pr`, `cut-release`, `rebuild-fixtures` —
|
||||
not `pr-helper`.
|
||||
- Description (the line the model sees) says **when to invoke**, not
|
||||
what the skill does.
|
||||
- `SKILL.md` under 200 lines; long skills split into stages.
|
||||
- Examples beat instructions.
|
||||
|
||||
Recommended installs:
|
||||
|
||||
```
|
||||
anthropic-skills:consolidate-memory periodic memory cleanup
|
||||
simplify review changed code for reuse/quality
|
||||
fewer-permission-prompts propose allowlist from transcripts
|
||||
review review a pull request
|
||||
security-review security pass on pending changes
|
||||
```
|
||||
|
||||
Review skills like PRs — read, run once on a real task, merge. Skills
|
||||
nobody runs after a month → archive (`.claude/skills/_archive/`).
|
||||
|
||||
### Sub-agents
|
||||
|
||||
Spawn a sub-agent (Claude `Agent` tool) when:
|
||||
|
||||
- Task needs cross-file search and you don't want results in main context.
|
||||
- You want a second independent read on a design or diff.
|
||||
- Work is genuinely parallel (e.g. researching three options).
|
||||
|
||||
Don't spawn for tasks the main agent can do in two tool calls.
|
||||
|
||||
### Sessions
|
||||
|
||||
- One task per session. New task → new session.
|
||||
- Long session, context bar filling → finish current step, summarize
|
||||
into a plan or PR draft, start fresh.
|
||||
- Don't `--continue` yesterday's session for a new topic. Stale context
|
||||
leaks in.
|
||||
|
||||
### Tool selection (mixing Claude Code + Codex)
|
||||
|
||||
Both fine; mild preferences:
|
||||
|
||||
- **Writing docs / specs** — Claude Code (this repo was written that way).
|
||||
- **Large refactors / cross-file features** — Claude Code (plan mode +
|
||||
sub-agents).
|
||||
- **Narrow edits, run a test, change a config** — Codex CLI (faster
|
||||
startup).
|
||||
- **In-IDE inline edits** — Codex IDE plugin or Cursor.
|
||||
|
||||
Don't run two tools editing the same file simultaneously — overwrites
|
||||
are hard to trace.
|
||||
|
||||
---
|
||||
|
||||
## 3. Git workflow
|
||||
|
||||
### Branches
|
||||
|
||||
- `main` (spec repos) / `dev` (product repos) is always shippable. No
|
||||
direct pushes, no exceptions.
|
||||
- Feature branches: `<owner>/<short-slug>` — `bai/auth-retry`,
|
||||
`bai/eval-agent-rerun`. Lowercase, hyphens, handle prefix.
|
||||
- Long-lived integration: `integration/<topic>` — only by team agreement.
|
||||
- Delete branches after merge.
|
||||
|
||||
### Commits
|
||||
|
||||
```
|
||||
<area>: <imperative summary under 60 chars>
|
||||
|
||||
<optional body — what changed and why, not how>
|
||||
```
|
||||
|
||||
- `<area>` is a directory or component, lowercase: `eval-agent`,
|
||||
`task_assistant`, `docs`, `git-workflow`.
|
||||
- Imperative: "add", "fix", "rename" — not "added" / "adding".
|
||||
- Body wraps at ~72 chars. Skip it for trivial commits.
|
||||
- One topic per commit. "and" in the summary → split.
|
||||
- Always include `Co-Authored-By` for AI-assisted commits.
|
||||
- English.
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
eval-agent: rerun failed tasks with stable seed
|
||||
docs: clarify branch naming
|
||||
task_assistant: drop unused legacy export path
|
||||
```
|
||||
|
||||
### Pull requests
|
||||
|
||||
- One PR per topic. Can't describe in one sentence → multiple PRs.
|
||||
- Title under 70 chars, same shape as commit summary.
|
||||
- Description structure: **Summary** (1 sentence + bullets if needed) /
|
||||
**Why** / **What changed** (bulleted by file or area) / **Test plan**
|
||||
(checkbox list, honest) / **Out of scope** (optional) / **Notes for
|
||||
reviewer** (optional, for surprising AI decisions). Add a
|
||||
`🤖 AI-assisted` trailer for AI-assisted PRs.
|
||||
- First push of a feature branch uses `-u`.
|
||||
- Open as draft once runnable. Review-as-you-go beats review-at-the-end.
|
||||
|
||||
### Review
|
||||
|
||||
Every PR reviewed before merge — own AI-assisted PRs included.
|
||||
|
||||
Reviewer:
|
||||
|
||||
1. Description matches diff? Surprises → ask.
|
||||
2. Read every changed file. Off-topic file → ask why it's in this PR.
|
||||
3. Run locally if not obviously correct from reading.
|
||||
4. New deps, schema changes, env vars, auth-touching code → block until
|
||||
justified.
|
||||
5. Comment on least-important issue first; merge-blocker last so it's
|
||||
clearly the gate.
|
||||
|
||||
Author follow-ups:
|
||||
|
||||
- Address every comment, even with "agreed, fixed in <commit>".
|
||||
- Disagree → push back in writing. Don't silently ignore.
|
||||
- Squash fixup commits before merge if history is noisy.
|
||||
|
||||
### Merging
|
||||
|
||||
- Squash for feature branches. Merge commits reserved for integration.
|
||||
- Final squash message follows commit format.
|
||||
- Delete the branch on merge.
|
||||
|
||||
### Tagging
|
||||
|
||||
Tags are dated: `YYYYMMDD`, with `-N` suffix for same-day reissues
|
||||
(`20260520-2`). Tag from `main`.
|
||||
|
||||
Rules:
|
||||
|
||||
- Annotated only (`git tag -a`).
|
||||
- Tag message summarizes what changed since the previous tag.
|
||||
- Tags are immutable once pushed. Wrong tag → cut a new one.
|
||||
- Don't tag on feature branches.
|
||||
- Max one tag per day, use `-N` for same-day reissues.
|
||||
|
||||
Cut a tag:
|
||||
|
||||
```bash
|
||||
git checkout main && git pull --ff-only
|
||||
git tag -a 20260520 -m "team-guide 20260520: bilingual policy"
|
||||
git push origin 20260520
|
||||
```
|
||||
|
||||
Inspect:
|
||||
|
||||
```bash
|
||||
git tag --sort=-creatordate
|
||||
git show 20260520
|
||||
git log --oneline 20260513..20260520
|
||||
```
|
||||
|
||||
When to cut a tag:
|
||||
|
||||
- Docs changed in a way teammates need to re-read.
|
||||
- A new convention is now in effect (not just proposed).
|
||||
- A library/ entry was added, removed, or restructured.
|
||||
|
||||
When **not** to cut a tag:
|
||||
|
||||
- Typos, formatting, link fixes → just push to `main`.
|
||||
- Drafts under discussion → use a PR.
|
||||
|
||||
Project repos in the workspace use their own tag schemes (typically
|
||||
semver `vX.Y.Z`). Each project documents its own scheme in its own
|
||||
`AGENTS.md`.
|
||||
|
||||
### Don'ts
|
||||
|
||||
- No `git push --force` to `main`. Period. To your own branch only if
|
||||
certain nobody pulled it.
|
||||
- No `--no-verify` to skip hooks. Fix what the hook reports.
|
||||
- No amending pushed commits. Add a new commit instead.
|
||||
- No deleting or moving pushed tags. Cut a new one.
|
||||
- No committing `.env`, secrets, or files >5 MB without a Git LFS
|
||||
conversation.
|
||||
- No `git add .` / `git add -A` when there are unrecognized untracked
|
||||
files. Stage by name.
|
||||
|
||||
---
|
||||
|
||||
## 4. Code & deliverable style
|
||||
|
||||
### Naming
|
||||
|
||||
- **Files** — lowercase. Docs hyphenated (`git-workflow.md`), Python
|
||||
underscored (`task_runner.py`), JS/TS kebab where ecosystem prefers.
|
||||
Match the surrounding project.
|
||||
- **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`,
|
||||
not `taskRunner`.
|
||||
- **Variables** — what they are, not their type. `users`, not
|
||||
`userArray`. `retryCount`, not `n`.
|
||||
- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
|
||||
- **Constants** — `UPPER_SNAKE_CASE` only at module level. Inside
|
||||
functions, plain `const`.
|
||||
- **No abbreviations** unless they're domain terms. `database`, not
|
||||
`db`. (`req`/`res` in Express is fine.)
|
||||
|
||||
### Comments
|
||||
|
||||
Default: none. Justified when **all** are true:
|
||||
|
||||
- *Why* is non-obvious from code.
|
||||
- A future reader would otherwise misread.
|
||||
- The code can't be made clearer (rename / extract / restructure).
|
||||
|
||||
Don't write:
|
||||
|
||||
- `// increment counter` next to `counter++`
|
||||
- `// added for the auth refactor` — belongs in the commit message
|
||||
- Block comments restating signatures
|
||||
- TODOs without owner or date
|
||||
|
||||
Do write:
|
||||
|
||||
- One-liners for non-obvious workarounds, with the *why*.
|
||||
- `# NOTE:` for behavior that would surprise a reader.
|
||||
- Module headers when the file does something the layout doesn't explain.
|
||||
|
||||
### File structure
|
||||
|
||||
- One concept per file. Can't summarize in one sentence → split.
|
||||
- Tests next to the code unless project already uses parallel test trees.
|
||||
- Generated files in `dist/`, `build/`, etc. — and `.gitignore`. Never
|
||||
edit a generated file.
|
||||
- Lockfiles always checked in.
|
||||
|
||||
### Errors
|
||||
|
||||
- Fail loudly at boundaries (user input, external APIs, file I/O).
|
||||
- Don't `try/except` to silence. Catch → handle.
|
||||
- Internal functions trust callers. Don't validate the same input three
|
||||
layers deep.
|
||||
- Logged errors include enough context to debug from logs alone.
|
||||
|
||||
### Tests
|
||||
|
||||
- Test behavior, not implementation. Behavior-preserving refactor that
|
||||
breaks a test → test was wrong.
|
||||
- One assertion per test ideally.
|
||||
- Fixtures next to the tests using them.
|
||||
- Slow / flaky tests get marked or quarantined, not silently retried.
|
||||
- New code without a test is incomplete unless project has no test
|
||||
infrastructure (rare, and a bug itself).
|
||||
|
||||
### READMEs
|
||||
|
||||
Every repo has one. In order:
|
||||
|
||||
1. **What is this?** One paragraph.
|
||||
2. **How do I run it?** Bash blocks.
|
||||
3. **How do I develop on it?** Code layout, conventions.
|
||||
4. **Where does data come from / go to?** Only if non-obvious.
|
||||
5. **Pointers.** Related repos, dashboards, docs.
|
||||
|
||||
Shorter than this is fine — drop sections that don't apply.
|
||||
|
||||
### Don'ts
|
||||
|
||||
- No third way to do something we already do two ways.
|
||||
- No config options "for flexibility" without a real use case. YAGNI.
|
||||
- No unrelated refactors in a feature PR. Open a separate one.
|
||||
- No optimization before measurement.
|
||||
|
||||
---
|
||||
|
||||
## 5. Team library
|
||||
|
||||
Narrower specs that don't fit cleanly in this file live under
|
||||
[`library/`](library/). Catalog: [`library/README.md`](library/README.md).
|
||||
|
||||
When an agent picks up a task, it should scan the catalog after reading
|
||||
this file and read entries that match. Each entry leads with a "When
|
||||
to read this" section so the decision is fast.
|
||||
|
||||
Current entries:
|
||||
|
||||
- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit,
|
||||
what not to, how to recover from leaked secrets.
|
||||
|
||||
Promotion criteria, layout, and adding rules: see
|
||||
[`library/README.md`](library/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 6. Planning cadence
|
||||
|
||||
1–3 person team. Lightest process that keeps us aligned.
|
||||
|
||||
### Weekly
|
||||
|
||||
- Async written sync (Monday morning). Each person posts:
|
||||
1. What I shipped last week (one line per item).
|
||||
2. What I'm picking up this week (one line per item).
|
||||
3. What's blocked or unclear (the only section worth reading carefully).
|
||||
- 30-minute live call mid-week. Agenda is the "blocked or unclear" lines.
|
||||
|
||||
### Per task
|
||||
|
||||
Before starting work that takes more than ~half a day:
|
||||
|
||||
1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*.
|
||||
2. Drop in PR description (draft PR fine) **before** writing code.
|
||||
3. If AI does most of the typing, the spec is also the prompt.
|
||||
|
||||
After:
|
||||
|
||||
1. PR description matches what shipped.
|
||||
2. Lessons future-you would want → Claude memory (feedback / project
|
||||
types). See [Memory](#memory).
|
||||
|
||||
### Quarterly
|
||||
|
||||
Half a day to:
|
||||
|
||||
- Re-read this `AGENTS.md`. Open PRs for what's stale.
|
||||
- Review skill catalog. Archive unused.
|
||||
- Run `consolidate-memory` on personal memory files.
|
||||
|
||||
### What planning is *not*
|
||||
|
||||
- Not Jira tickets. Two people don't need a board.
|
||||
- Not Gantt charts. Need one → building the wrong thing.
|
||||
- Not status theater. Monday post is for spotting blocks, not proving
|
||||
you worked.
|
||||
|
||||
---
|
||||
|
||||
## 7. Handoff
|
||||
|
||||
Task packages, deliverables, work transfers between team members or to
|
||||
external consumers.
|
||||
|
||||
### Why this matters
|
||||
|
||||
Handoff failures cost more than the original work. A package that's
|
||||
"obvious" to the author is a half day of confusion for the recipient.
|
||||
Handoff is **part of the deliverable**, not afterthought packaging.
|
||||
|
||||
### Two kinds
|
||||
|
||||
- **Internal** — passing work to a teammate or future-you. Branch, PR,
|
||||
half-finished prototype.
|
||||
- **External** — versioned artifact to a partner / customer / downstream.
|
||||
Zip, dataset, release.
|
||||
|
||||
Both use the [handoff checklist](#handoff-checklist) below. External has
|
||||
higher bar.
|
||||
|
||||
### Task package layout
|
||||
|
||||
```
|
||||
<package>/
|
||||
├── README.md ← what this is, who it's for, how to use
|
||||
├── CHANGELOG.md ← what changed since last version
|
||||
├── VERIFICATION.md ← counts, checksums, sanity checks
|
||||
├── manifest.json ← machine-readable metadata
|
||||
├── data/ ← the actual deliverable
|
||||
└── scripts/ ← only what's needed to use the package
|
||||
```
|
||||
|
||||
`manifest.json` minimum fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "praxis-sample-5",
|
||||
"version": "0.5.0",
|
||||
"generated_at": "2026-05-18T17:00:00Z",
|
||||
"source_commit": "<full sha>",
|
||||
"source_repo": "<git remote url>",
|
||||
"record_count": 1234,
|
||||
"schema_version": "1.0"
|
||||
}
|
||||
```
|
||||
|
||||
Can't fill a field → `null` and explain in README. **Never make one up.**
|
||||
|
||||
### Internal handoff
|
||||
|
||||
Before handoff:
|
||||
|
||||
- PR description is current. Summary describes what shipped, not what
|
||||
was attempted.
|
||||
- Test plan in PR template filled honestly. Untested → say so, don't
|
||||
bury.
|
||||
- Surprising AI-assisted decisions → `## Notes for reviewer`. "AI tried
|
||||
X first, didn't work because Y, working approach is Z" — saves the
|
||||
reviewer a re-derivation.
|
||||
- Local-only state (env vars, scratch data) documented or scripted.
|
||||
"Works on my machine" is not a handoff.
|
||||
|
||||
The recipient should be able to: `git checkout` the branch → read PR
|
||||
description → run test plan → form an opinion — **without messaging you.**
|
||||
|
||||
### External handoff (additional bar)
|
||||
|
||||
- **Reproducibility.** Someone with source access can rebuild from the
|
||||
commit hash in `manifest.json`. Test once before first release.
|
||||
- **Verification report.** Machine-checkable (JSON or similar) showing
|
||||
pre-ship checks passed.
|
||||
- **Provenance.** AI-generated → record model and human-in-loop steps.
|
||||
For debugging six months later, not ceremony.
|
||||
- **License & attribution.** Even for internal partners.
|
||||
|
||||
### What not to ship
|
||||
|
||||
- Files >500 MB without a delivery-channel conversation.
|
||||
- Real PII unless that's explicitly the deal.
|
||||
- `.env`, secrets, API keys, internal hostnames.
|
||||
- "Final final v3" filenames. Use the version field. If it's `final`,
|
||||
it's `v1.0`.
|
||||
- A package without a README. Even a one-line README beats none.
|
||||
|
||||
### Receiving a handoff
|
||||
|
||||
1. Read the README first, fully. Resist running scripts.
|
||||
2. Run the verification report. Fails → stop and message the sender
|
||||
before doing anything else.
|
||||
3. Note any surprise — naming, missing files, version mismatch — and
|
||||
send back within a day. Drift gets worse with silence.
|
||||
|
||||
### Handoff checklist
|
||||
|
||||
Copy into the package (external handoff) or PR description (internal).
|
||||
Fill it before declaring handoff done.
|
||||
|
||||
```markdown
|
||||
## Identity
|
||||
- Name:
|
||||
- Version: <e.g. v0.5.0 or commit sha or tag>
|
||||
- Generated at: <ISO timestamp>
|
||||
- Source repo:
|
||||
- Source commit: <full sha>
|
||||
- Owner: <name>
|
||||
- Recipient: <name or team>
|
||||
|
||||
## Contents
|
||||
- [ ] README.md — what this is, how to use it
|
||||
- [ ] CHANGELOG.md — diff vs previous version (or "first release")
|
||||
- [ ] manifest.json — all fields filled or explicitly null
|
||||
- [ ] VERIFICATION.md — what was checked, results
|
||||
- [ ] Data / artifacts
|
||||
- [ ] Scripts (only what's required to use the package)
|
||||
|
||||
## Verification
|
||||
- [ ] Record / file counts match expected
|
||||
- [ ] Checksums computed and recorded
|
||||
- [ ] Sanity checks pass (list them)
|
||||
- [ ] No secrets, .env, or credentials
|
||||
- [ ] No PII unless explicitly part of deliverable
|
||||
- [ ] Total size reasonable for delivery channel
|
||||
|
||||
## Reproducibility (external handoff only)
|
||||
- [ ] Confirmed someone with repo access can rebuild from source_commit
|
||||
- [ ] Build / generation command documented in README.md
|
||||
- [ ] External dependencies pinned
|
||||
|
||||
## Provenance (if AI-assisted)
|
||||
- Model used:
|
||||
- Human-in-loop steps:
|
||||
- Notable AI-assisted decisions:
|
||||
|
||||
## Known limitations
|
||||
- <…>
|
||||
|
||||
## Recipient instructions
|
||||
- [ ] Read README.md first
|
||||
- [ ] Run verification report; if fails, stop and contact sender
|
||||
- [ ] Confirm receipt within <X days>
|
||||
- [ ] Report any surprises within <X days>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Working directory expectations (this repo)
|
||||
|
||||
- Small repo (~10 files). `Read` everything before acting; no need to
|
||||
spawn a sub-agent for exploration.
|
||||
- Don't introduce `package.json`, `Makefile`, CI configs, or other
|
||||
toolchain files unless explicitly asked. This is a docs repo.
|
||||
@@ -1,46 +1 @@
|
||||
# CLAUDE.md — team-guide
|
||||
|
||||
This repo holds our team's working agreements. When editing it, behave like
|
||||
a careful technical writer, not a coder.
|
||||
|
||||
## Context
|
||||
|
||||
- **Audience**: 1–3 person team, AI-assisted development ("vibe coding").
|
||||
- **Language**: English. All docs, all commits, all PR titles.
|
||||
- **Tone**: short, declarative, opinionated. No fluff, no hedging, no marketing voice.
|
||||
|
||||
## Editing rules
|
||||
|
||||
- One rule per bullet. If a rule needs a paragraph of justification, split
|
||||
the rule out and put the justification in a *Why* line.
|
||||
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only when
|
||||
the rule is non-obvious. Skip them when the rule speaks for itself.
|
||||
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
|
||||
- Keep each doc under ~150 lines. If it's growing past that, the doc is
|
||||
probably two docs.
|
||||
- Examples beat prose. Prefer a 3-line code block over a paragraph
|
||||
describing the code.
|
||||
|
||||
## What goes where
|
||||
|
||||
| If you're writing about… | Put it in… |
|
||||
| ---------------------------------------- | -------------------------------- |
|
||||
| How humans and AI split a task | `docs/01-vibe-coding.md` |
|
||||
| Claude Code config (CLAUDE.md, hooks…) | `docs/02-claude-code.md` |
|
||||
| Branches, commits, PRs | `docs/03-git-workflow.md` |
|
||||
| Which skills to install, planning cadence| `docs/04-skills-and-planning.md` |
|
||||
| Naming, comments, file structure | `docs/05-code-style.md` |
|
||||
| Task packages, handoff between members | `docs/06-handoff.md` |
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- Don't add a doc for a rule we've used once. Wait until it's bitten us
|
||||
twice — then write it.
|
||||
- Don't write process for processes' sake. If nobody would read or follow
|
||||
it, don't write it.
|
||||
- Don't quote external sources at length (license/copyright). Link instead.
|
||||
|
||||
## Commits
|
||||
|
||||
- Commit message: `<area>: <imperative summary>` — e.g. `git-workflow: clarify branch naming`.
|
||||
- One topic per commit. If a commit message has "and" in it, it's two commits.
|
||||
@AGENTS.md
|
||||
@@ -1,58 +0,0 @@
|
||||
# team-guide
|
||||
|
||||
> 中文版:[README.md](README.md)
|
||||
|
||||
Working agreements for our team's AI-assisted ("vibe coding") development.
|
||||
Small team, English docs, opinionated but light.
|
||||
|
||||
## What this repo is
|
||||
|
||||
A single source of truth for **how we work**, not what we build. It covers:
|
||||
|
||||
- How we use Claude Code (CLAUDE.md, permissions, hooks, memory, skills)
|
||||
- How we collaborate with AI when writing code (vibe coding norms)
|
||||
- Git workflow (branches, commits, PRs, review)
|
||||
- Skill management and project planning rhythm
|
||||
- Code & deliverable style (naming, comments, READMEs, task packages, handoffs)
|
||||
|
||||
Every doc is short. If a rule needs more than half a page to justify, it
|
||||
probably isn't a rule yet — it's a discussion.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
team-guide/
|
||||
├── README.md ← you are here
|
||||
├── CLAUDE.md ← context Claude Code loads when working in this repo
|
||||
├── docs/
|
||||
│ ├── 01-vibe-coding.md ← how humans + AI split the work
|
||||
│ ├── 02-claude-code.md ← CLAUDE.md / permissions / hooks / memory / skills
|
||||
│ ├── 03-git-workflow.md ← branches, commits, PRs, review
|
||||
│ ├── 04-skills-and-planning.md ← skill catalog + planning cadence
|
||||
│ ├── 05-code-style.md ← naming, comments, structure
|
||||
│ └── 06-handoff.md ← task packages, handoff checklists
|
||||
└── templates/
|
||||
├── CLAUDE.md.template
|
||||
├── README.md.template
|
||||
├── PR_DESCRIPTION.template.md
|
||||
└── HANDOFF_CHECKLIST.template.md
|
||||
```
|
||||
|
||||
## How to use it
|
||||
|
||||
1. **New team member** — read `docs/01-vibe-coding.md` and `docs/03-git-workflow.md` first. The rest is reference.
|
||||
2. **Starting a new project** — copy the templates from `templates/` into the new repo and fill them in. Drop a top-level `CLAUDE.md` that points back here.
|
||||
3. **Disagreeing with a rule** — open a PR against this repo. Don't silently diverge.
|
||||
|
||||
## Versioning
|
||||
|
||||
Releases are tagged by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a
|
||||
snapshot of `main` from that day, suitable for "this is the version we
|
||||
agreed to follow." See `docs/03-git-workflow.md` for the tagging rules.
|
||||
|
||||
- Latest tag: see [`git tag --sort=-creatordate`](https://git.simgreek.com/simgreek/team-guide/tags) on the remote
|
||||
- `main` is always the working copy; tags are checkpoints
|
||||
|
||||
## License
|
||||
|
||||
Internal.
|
||||
@@ -1,68 +1,92 @@
|
||||
# team-guide
|
||||
|
||||
> English: [README.en.md](README.en.md)
|
||||
我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
|
||||
|
||||
我们小团队的 AI 协作(vibe coding)开发约定。
|
||||
1–3 人规模,英文写文档,规则不多但都是真踩过的坑。
|
||||
完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
|
||||
这份 README 是给人的导览,知道去哪查、怎么参与就行。
|
||||
|
||||
## 这个仓库是什么
|
||||
## 这个仓库给谁用
|
||||
|
||||
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
|
||||
**给 AI 用**。每个团队项目里 AI 开干前应该先读 team-guide:
|
||||
|
||||
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
|
||||
- 写代码时人和 AI 怎么分工(vibe coding 守则)
|
||||
- Git 工作流(分支、commit、PR、review)
|
||||
- Skill 管理与项目规划节奏
|
||||
- 代码与产出风格(命名、注释、README、任务包、handoff)
|
||||
1. 读 [`AGENTS.md`](AGENTS.md)——团队通用规则
|
||||
2. 扫 [`library/README.md`](library/README.md)——按当前任务挑相关条目读
|
||||
3. 再读项目自己的 `AGENTS.md`——只放项目特定的东西
|
||||
|
||||
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
|
||||
项目自己的 `AGENTS.md` **不重复**这里的规则,引用就行,保持小而具体。
|
||||
|
||||
## 怎么用(人)
|
||||
|
||||
1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
|
||||
2. **新项目** —— 在新仓库根目录放 `AGENTS.md`(骨架在 [AGENTS.md](AGENTS.md) 的 Claude Code & Codex 节),再放一行 `@AGENTS.md` 的 `CLAUDE.md`。让两边 AI 工具读同一份项目说明。
|
||||
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
|
||||
|
||||
## 语言策略
|
||||
|
||||
- **给人看的(中文)**:本 README。
|
||||
- **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、`library/` 下所有内容。
|
||||
- **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
|
||||
|
||||
理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
team-guide/
|
||||
├── README.md ← 中文版(你正在看)
|
||||
├── README.en.md ← English version
|
||||
├── CLAUDE.md ← Claude Code 在本仓库工作时加载的上下文
|
||||
├── docs/
|
||||
│ ├── 01-vibe-coding.md ← 人 + AI 怎么分工
|
||||
│ ├── 02-claude-code.md ← CLAUDE.md / permission / hook / memory / skill
|
||||
│ ├── 03-git-workflow.md ← 分支、commit、PR、review、tag
|
||||
│ ├── 04-skills-and-planning.md ← skill 目录 + 规划节奏
|
||||
│ ├── 05-code-style.md ← 命名、注释、结构
|
||||
│ └── 06-handoff.md ← 任务包、handoff 清单
|
||||
└── templates/
|
||||
├── CLAUDE.md.template
|
||||
├── README.md.template
|
||||
├── PR_DESCRIPTION.template.md
|
||||
└── HANDOFF_CHECKLIST.template.md
|
||||
├── README.md ← 你正在看(中文,给人)
|
||||
├── AGENTS.md ← 全部团队规则(英文,给 AI)
|
||||
├── CLAUDE.md ← 一行 @AGENTS.md import
|
||||
└── library/ ← 窄主题专项规范目录
|
||||
├── README.md ← catalog
|
||||
└── git-upload/ ← 第一篇:什么该传什么不该传
|
||||
└── SPEC.md
|
||||
```
|
||||
|
||||
## 怎么用
|
||||
[`AGENTS.md`](AGENTS.md) 内含:
|
||||
项目背景 · 编辑规则 · 语言策略 · Vibe coding · Claude Code & Codex 配置 ·
|
||||
Git 工作流 · 代码与产出风格 · Team library 索引 · 规划节奏 · Handoff。
|
||||
|
||||
1. **新成员** —— 先读 [`docs/01-vibe-coding.md`](docs/01-vibe-coding.md) 和 [`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。
|
||||
2. **新项目** —— 从 `templates/` 复制模板到新仓库填上,再在新仓库根目录放一个 `CLAUDE.md` 指回这里。
|
||||
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
|
||||
## Library 怎么扩
|
||||
|
||||
## 文档语言约定
|
||||
碰到一个跨项目的具体话题、AGENTS.md 里塞进去会拖肿(比如"git 上传到底什么该传"、"PII 处理"、"eval 报告格式"),就在 `library/` 下开一个子目录写 `SPEC.md`。
|
||||
|
||||
- 仓库内所有 `.md` 用**英文**,包括 commit message、PR 标题、tag 注释。
|
||||
- 这个 README 提供中文入口;剩下的内容直接读英文版本。
|
||||
- 跟外部团队/客户的交付物按对方语言来——本仓库的规则只管内部。
|
||||
收录标准(同时满足):
|
||||
1. 至少踩过两次。
|
||||
2. 比 AGENTS.md 通用规则窄,inline 进去会拖肿。
|
||||
3. 步骤稳定到能写下来。
|
||||
|
||||
每加一条在 [`library/README.md`](library/README.md) 的 catalog 表里加一行"什么时候读它"。
|
||||
|
||||
## 版本管理
|
||||
|
||||
按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。
|
||||
本仓库(规范类)按日期打 tag:`YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
|
||||
|
||||
- `main` 永远是当前工作副本,随时合并。
|
||||
- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
|
||||
- 大改写新 tag,不动旧 tag。
|
||||
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
|
||||
通用规则:
|
||||
|
||||
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tagging 一节。
|
||||
- `main` 永远是当前工作副本。
|
||||
- 只用 annotated tag(`git tag -a`)。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
|
||||
- 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`)就行。
|
||||
|
||||
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
|
||||
项目仓库自己(task_assistant 这类)用各自的 tag 方案(通常是 semver `vX.Y.Z`),写在项目自己的 `AGENTS.md` 里。
|
||||
|
||||
具体命令和什么时候切 tag——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 节。
|
||||
|
||||
## 几条最容易踩的线(速查)
|
||||
|
||||
完整版在 AGENTS.md 和 library/,这里挑人最常忘的:
|
||||
|
||||
- 长 session 的上下文会污染输出,新任务开新 session
|
||||
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
|
||||
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
|
||||
- AI 试同一个方案两次报同样的错——叫停,自己上
|
||||
- `git add .` 前先 `git status` 看一眼,确认没有不该传的文件
|
||||
- 提交前 `git diff --cached` 扫一眼;密钥误提交的应急流程在 [`library/git-upload/SPEC.md`](library/git-upload/SPEC.md)
|
||||
|
||||
## 远端
|
||||
|
||||
[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) ·
|
||||
[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -1,84 +0,0 @@
|
||||
# 01 — Vibe coding
|
||||
|
||||
How humans and AI split the work on this team.
|
||||
|
||||
## The premise
|
||||
|
||||
Claude Code writes most of the code. Humans steer: framing problems,
|
||||
making decisions, deciding what's good enough to ship. We're not racing
|
||||
the AI — we're using it to skip typing so we can spend more time
|
||||
thinking.
|
||||
|
||||
## The split
|
||||
|
||||
**Claude does:**
|
||||
|
||||
- Read code and explain it
|
||||
- Write first-pass implementations against a clear spec
|
||||
- Refactor mechanically (renames, extractions, type changes)
|
||||
- Run tests, builds, linters; iterate on errors
|
||||
- Generate boilerplate (configs, fixtures, templates, CRUD)
|
||||
- Search across the workspace and summarize findings
|
||||
|
||||
**Humans do:**
|
||||
|
||||
- Decide what to build and why
|
||||
- Frame the spec before Claude touches code
|
||||
- Approve any change with non-local consequences (deps, schema, infra, auth, secrets)
|
||||
- Read every diff before merging
|
||||
- Make the call when Claude has tried twice and is going in circles
|
||||
- Write the commit message and PR description (Claude drafts; you sign off)
|
||||
|
||||
If a task feels like it's drifting toward "Claude decides", stop and
|
||||
write a short spec yourself first.
|
||||
|
||||
## Prompt habits
|
||||
|
||||
- **Frame, don't dictate.** Tell Claude the goal, the constraints, and
|
||||
what you've already ruled out. Don't prescribe steps unless the steps
|
||||
are the point.
|
||||
- **Name the file.** "Fix the bug in `eval-agent/runner.py`" is better
|
||||
than "fix the bug." Save Claude a search.
|
||||
- **Say what done looks like.** "Tests pass and the new flag defaults to
|
||||
off" — measurable. "Make it cleaner" — not.
|
||||
- **One task per turn.** If you have three unrelated asks, send three
|
||||
messages or open three sessions. Mixed contexts produce mixed results.
|
||||
- **Push back on bad output.** If the diff is wrong, say so plainly and
|
||||
point at the part that's wrong. Don't accept code you wouldn't write
|
||||
yourself.
|
||||
|
||||
## When to stop and take over
|
||||
|
||||
Stop letting Claude drive when:
|
||||
|
||||
- It's failed the same approach twice and the error is unchanged.
|
||||
- It's adding code "for safety" that the task didn't ask for.
|
||||
- The diff has grown past what you can read in one sitting.
|
||||
- You can't explain the change to a teammate without re-reading the diff.
|
||||
- It's about to do something irreversible (delete data, force-push,
|
||||
change auth) — confirm explicitly.
|
||||
|
||||
If you stop and take over, write down *why* in the PR description so
|
||||
the next person doesn't repeat the loop.
|
||||
|
||||
## Verifying AI output
|
||||
|
||||
Treat every Claude diff like a PR from a fast junior:
|
||||
|
||||
1. Does it build?
|
||||
2. Do the tests pass — and do new tests actually test the new code?
|
||||
3. Did it touch files outside the stated scope? Look at every one.
|
||||
4. Did it add deps? Check the lockfile diff.
|
||||
5. Read every comment Claude added. Half of them are noise — delete those.
|
||||
6. Run the feature end-to-end if it's user-facing. Type checks ≠ working software.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- **Snowballing context.** Long sessions accumulate stale assumptions.
|
||||
Start a new session for a new task.
|
||||
- **Approval-by-default.** "Looks good" without reading the diff is how
|
||||
bugs ship. Read it.
|
||||
- **Outsourcing the spec.** "Figure out what we should do" is not a
|
||||
prompt — it's avoidance.
|
||||
- **Letting AI rewrite history.** If Claude wants to refactor unrelated
|
||||
code "while we're here", say no. Open a separate task.
|
||||
@@ -1,129 +0,0 @@
|
||||
# 02 — Claude Code
|
||||
|
||||
How we configure and use Claude Code across projects.
|
||||
|
||||
## Configuration files
|
||||
|
||||
Each project should have:
|
||||
|
||||
```
|
||||
<repo>/
|
||||
├── CLAUDE.md ← project context (committed)
|
||||
└── .claude/
|
||||
├── settings.json ← shared settings (committed)
|
||||
├── settings.local.json ← personal overrides (gitignored)
|
||||
└── skills/ ← project-local skills (committed)
|
||||
```
|
||||
|
||||
`settings.local.json` is **always** gitignored. Personal API keys, local
|
||||
paths, and individual hook tweaks live there.
|
||||
|
||||
## CLAUDE.md content
|
||||
|
||||
Every `CLAUDE.md` answers, in this order:
|
||||
|
||||
1. **What is this project?** Two sentences max.
|
||||
2. **How do I run it?** Build, test, lint commands as bash blocks.
|
||||
3. **Architecture in one paragraph.** Where the entry points are and
|
||||
how data flows. No diagrams unless they save words.
|
||||
4. **Conventions specific to this repo.** Naming, layout, patterns
|
||||
that aren't obvious from the code.
|
||||
5. **Don'ts.** Things Claude has gotten wrong before. One line each.
|
||||
|
||||
A new contributor (human or AI) should be productive after reading it
|
||||
once. If a `CLAUDE.md` is over 100 lines, it's drifted into documentation
|
||||
and should be split.
|
||||
|
||||
Use `templates/CLAUDE.md.template` as the starting point.
|
||||
|
||||
## Permissions
|
||||
|
||||
Default permission posture: **prompt for everything risky, allow read-only
|
||||
freely.**
|
||||
|
||||
In `.claude/settings.json`, allow these without prompting:
|
||||
|
||||
- All `Read`, `Glob`, `Grep` tools
|
||||
- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`, `Bash(git branch)`
|
||||
- Project-specific read-only commands (e.g. `Bash(npm test)`, `Bash(pytest)`)
|
||||
|
||||
Always prompt for:
|
||||
|
||||
- File `Edit` / `Write` outside the working tree
|
||||
- `Bash` with destructive verbs (`rm`, `mv`, `git push`, `git reset --hard`, package installs)
|
||||
- Any MCP tool that talks to a remote service
|
||||
|
||||
When you find yourself approving the same prompt over and over, run the
|
||||
`fewer-permission-prompts` skill — it scans your transcripts and
|
||||
proposes an allowlist.
|
||||
|
||||
## Hooks
|
||||
|
||||
Hooks are how the harness enforces rules automatically — Claude itself
|
||||
won't reliably remember a "from now on…" instruction across sessions.
|
||||
|
||||
Use hooks for:
|
||||
|
||||
- Auto-formatting on file edit (Prettier, ruff, gofmt)
|
||||
- Blocking edits to protected paths (`.env`, generated files, `dist/`)
|
||||
- Auto-running tests after a write to a known test path
|
||||
- Notifying on session stop / long-running task completion
|
||||
|
||||
Don't use hooks for:
|
||||
|
||||
- One-off checks ("just remember to do X this week")
|
||||
- Anything that depends on Claude's judgment ("only run if it makes sense")
|
||||
|
||||
Configure via the `update-config` skill or edit `.claude/settings.json`
|
||||
directly. Document each hook with a one-line comment in the JSON.
|
||||
|
||||
## Memory
|
||||
|
||||
The harness has a per-machine memory system. Use it for:
|
||||
|
||||
- **User**: who you are, your role, your preferences.
|
||||
- **Feedback**: corrections you've given Claude that should stick across
|
||||
sessions (with the *why*).
|
||||
- **Project**: facts about ongoing work that aren't in the code (deadlines,
|
||||
stakeholder decisions, why a refactor is happening).
|
||||
- **Reference**: pointers to external resources (Linear projects, Grafana
|
||||
dashboards, internal wikis).
|
||||
|
||||
Don't put memory content in `CLAUDE.md`. CLAUDE.md is project context,
|
||||
shared with the team. Memory is personal, per-machine, and lives outside
|
||||
the repo.
|
||||
|
||||
Don't use memory as a notes app. If it's task-scoped, it goes in a plan or
|
||||
PR description.
|
||||
|
||||
## Skills
|
||||
|
||||
Skills live in three places:
|
||||
|
||||
- **User skills** (`~/.claude/skills/`) — installed once, available everywhere
|
||||
- **Project skills** (`<repo>/.claude/skills/`) — committed, shared with team
|
||||
- **Plugin skills** — installed via marketplace
|
||||
|
||||
Promote a workflow to a skill once you've done it the same way three
|
||||
times. See `docs/04-skills-and-planning.md` for the catalog.
|
||||
|
||||
## Sub-agents
|
||||
|
||||
Spawn a sub-agent (via the `Agent` tool) when:
|
||||
|
||||
- The task needs a search across many files and you don't want the
|
||||
results in your main context.
|
||||
- You want a second, independent read on a design or diff.
|
||||
- The work is genuinely parallel (e.g. researching three options).
|
||||
|
||||
Don't spawn sub-agents for tasks the main agent can do in two tool calls.
|
||||
The handoff overhead isn't free.
|
||||
|
||||
## Sessions
|
||||
|
||||
- One task per session. Open a new session for a new task.
|
||||
- If a session is running long and the context bar is filling, finish
|
||||
the current step, summarize state into a plan or PR draft, then start
|
||||
fresh.
|
||||
- Don't use `--continue` to resume a session from yesterday on a new
|
||||
topic. The stale context will leak in.
|
||||
@@ -1,137 +0,0 @@
|
||||
# 03 — Git workflow
|
||||
|
||||
Small team, light process. Branches, commits, PRs, review.
|
||||
|
||||
## Branches
|
||||
|
||||
- `main` is always shippable. No direct pushes. No exceptions.
|
||||
- Feature branches: `<owner>/<short-slug>` — e.g. `bai/auth-retry`,
|
||||
`bai/eval-agent-rerun`. Lowercase, hyphens, your handle as prefix.
|
||||
- Long-lived integration branches: `integration/<topic>` — only with
|
||||
team agreement.
|
||||
- Delete branches after merge. Old branches confuse search.
|
||||
|
||||
## Commits
|
||||
|
||||
Format:
|
||||
|
||||
```
|
||||
<area>: <imperative summary under 60 chars>
|
||||
|
||||
<optional body — what changed and why, not how>
|
||||
```
|
||||
|
||||
- `<area>` is a directory or component, lowercase: `eval-agent`,
|
||||
`task_assistant`, `docs`, `git-workflow`.
|
||||
- Imperative: "add", "fix", "rename" — not "added" / "adding".
|
||||
- Body wraps at ~72 chars. Skip it for trivial commits.
|
||||
- One topic per commit. "and" in the summary means split it.
|
||||
- AI-assisted commits get the `Co-Authored-By` trailer Claude Code adds
|
||||
by default. Don't strip it.
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
eval-agent: rerun failed tasks with stable seed
|
||||
docs: clarify branch naming in git-workflow
|
||||
task_assistant: drop unused legacy export path
|
||||
```
|
||||
|
||||
## Pull requests
|
||||
|
||||
- One PR per topic. If you can't describe it in one sentence, it's
|
||||
multiple PRs.
|
||||
- Title under 70 chars, same shape as a commit summary.
|
||||
- Description uses `templates/PR_DESCRIPTION.template.md`.
|
||||
- Push to your feature branch with `-u` the first time so it tracks
|
||||
remote.
|
||||
- Open the PR as soon as you have something runnable, even if it's a
|
||||
draft. Review-as-you-go beats review-at-the-end.
|
||||
|
||||
## Review
|
||||
|
||||
We review every PR before merge, even our own AI-assisted ones.
|
||||
|
||||
Reviewer checks:
|
||||
|
||||
1. Does the description match the diff? If the diff has surprises, ask.
|
||||
2. Read every file changed. If a file isn't related to the stated
|
||||
topic, ask why it's in the PR.
|
||||
3. Run the change locally if it's not obviously correct from reading.
|
||||
4. New deps, schema changes, env vars, or auth-touching code → block
|
||||
until justified.
|
||||
5. Comment on the *least* important issue first; save the merge-blocker
|
||||
for last so it's clearly the gate.
|
||||
|
||||
Author follow-ups:
|
||||
|
||||
- Address every comment, even with "agreed, fixed in <commit>".
|
||||
- If you disagree, push back in writing. Don't silently ignore.
|
||||
- Squash fixup commits before merge if the history is noisy.
|
||||
|
||||
## Merging
|
||||
|
||||
- Squash for feature branches. Merge commits are reserved for
|
||||
integration branches.
|
||||
- Final squash message follows the commit format above. The PR title is
|
||||
usually the right starting point.
|
||||
- Delete the branch on merge.
|
||||
|
||||
## Tagging (versioning)
|
||||
|
||||
We tag by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a snapshot of
|
||||
`main` worth pointing at — "this is the version we agreed to follow."
|
||||
|
||||
Rules:
|
||||
|
||||
- Tag only on `main`. Tagging a feature branch is a smell.
|
||||
- One tag per day max. If you cut a second one the same day, suffix with
|
||||
`-N`: `20260520-2`, `20260520-3`.
|
||||
- Tag messages are annotated, not lightweight. Use `git tag -a` and
|
||||
write one or two sentences about what changed since the last tag.
|
||||
- A tag, once pushed, is immutable. No deleting, no moving, no force-tag.
|
||||
If the tag is wrong, cut a new one.
|
||||
- Tag the commit, push the tag, and announce the tag name. That's the
|
||||
release.
|
||||
|
||||
Cut a tag:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull --ff-only
|
||||
git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags"
|
||||
git push origin 20260520
|
||||
```
|
||||
|
||||
List / inspect:
|
||||
|
||||
```bash
|
||||
git tag --sort=-creatordate # newest first
|
||||
git show 20260520 # show what's in a tag
|
||||
git log --oneline 20260513..20260520 # what changed between tags
|
||||
```
|
||||
|
||||
When to cut a tag:
|
||||
|
||||
- The docs in this repo changed in a way teammates need to read.
|
||||
- A template was added, removed, or restructured.
|
||||
- A new convention is now in effect (not just proposed).
|
||||
|
||||
When NOT to cut a tag:
|
||||
|
||||
- Typo fixes, formatting, broken links → just push to `main`.
|
||||
- Drafts under discussion → use a PR, don't tag.
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- No `git push --force` to `main`. Period. To your own branch, only if
|
||||
nobody else has pulled it.
|
||||
- No `--no-verify` to skip hooks. Fix what the hook is complaining
|
||||
about.
|
||||
- No amending pushed commits. Once it's on the remote, add a new commit.
|
||||
- No deleting or moving tags after they've been pushed. Cut a new one
|
||||
instead.
|
||||
- No committing `.env`, credentials, or files larger than ~5 MB without
|
||||
a Git LFS conversation first.
|
||||
- No staging with `git add .` or `git add -A` when there are untracked
|
||||
files you don't recognize. Stage by name.
|
||||
@@ -1,112 +0,0 @@
|
||||
# 04 — Skills and planning
|
||||
|
||||
How we manage the skill catalog and how we plan work as a small team.
|
||||
|
||||
## Skill catalog
|
||||
|
||||
A "skill" is a reusable, named workflow Claude Code can invoke. We keep
|
||||
three catalogs:
|
||||
|
||||
- **Personal** (`~/.claude/skills/`) — private, per developer.
|
||||
- **Team** (`<repo>/.claude/skills/`) — committed, shared via the project.
|
||||
- **Bundled / plugin** — installed from a marketplace.
|
||||
|
||||
### When to make a skill
|
||||
|
||||
Promote a workflow to a skill when **all three** are true:
|
||||
|
||||
1. You've done it the same way three times.
|
||||
2. The steps are stable enough to write down.
|
||||
3. Someone else on the team would do it the same way if shown.
|
||||
|
||||
If only two are true, leave it as a prompt snippet in your notes.
|
||||
|
||||
### Skill design rules
|
||||
|
||||
- One skill, one job. Skills that branch on "what does the user want?"
|
||||
are two skills.
|
||||
- Name the skill as a verb phrase: `review-pr`, `cut-release`,
|
||||
`rebuild-fixtures`. Not `pr-helper`.
|
||||
- Description (the one-liner the model sees) must say *when to invoke*,
|
||||
not what the skill does. The model decides on the *when*.
|
||||
- Keep `SKILL.md` under 200 lines. Long skills get broken into stages.
|
||||
- Examples beat instructions. Show one good run.
|
||||
|
||||
### Reviewing skills
|
||||
|
||||
Treat a new skill like a PR: read it, run it once on a real task, then
|
||||
merge. Skills that nobody runs after a month get archived (move to
|
||||
`.claude/skills/_archive/`).
|
||||
|
||||
### Active skills (this team)
|
||||
|
||||
Maintain this list as we go. Drop a one-line description and the path.
|
||||
|
||||
```
|
||||
# Personal recommendations (install with marketplace or copy):
|
||||
# anthropic-skills:consolidate-memory — periodic memory cleanup
|
||||
# simplify — review changed code for reuse/quality
|
||||
# fewer-permission-prompts — propose allowlist from transcripts
|
||||
# review — review a pull request
|
||||
# security-review — security pass on pending changes
|
||||
|
||||
# Team skills (in this repo):
|
||||
# (none yet — add as we promote workflows)
|
||||
```
|
||||
|
||||
## Planning cadence
|
||||
|
||||
We're 1–3 people. Process should be the lightest thing that keeps us
|
||||
aligned. Right now that's:
|
||||
|
||||
### Weekly
|
||||
|
||||
- One short async written sync (Mon morning). Each person posts:
|
||||
1. What I shipped last week (one line per item).
|
||||
2. What I'm picking up this week (one line per item).
|
||||
3. What's blocked or unclear (the only section worth reading carefully).
|
||||
- 30-minute live call mid-week. Agenda comes from the "blocked or
|
||||
unclear" lines.
|
||||
|
||||
### Per-task
|
||||
|
||||
Before starting work that will take more than ~half a day:
|
||||
|
||||
1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*.
|
||||
2. Drop it in the PR description (draft PR is fine) **before** writing
|
||||
code.
|
||||
3. If Claude is going to do most of the typing, the spec is also the
|
||||
prompt — paste it in.
|
||||
|
||||
After finishing:
|
||||
|
||||
1. PR description updated to match what actually shipped.
|
||||
2. Anything you learned that future-you would want goes into Claude
|
||||
memory (feedback / project type) — see `docs/02-claude-code.md`.
|
||||
|
||||
### Per-quarter
|
||||
|
||||
One half-day to:
|
||||
|
||||
- Re-read this `team-guide` repo. Open PRs for what's stale.
|
||||
- Review the skill catalog. Archive what we don't use.
|
||||
- Run `consolidate-memory` against personal memory files.
|
||||
|
||||
## Project structure
|
||||
|
||||
When starting a new project under this workspace:
|
||||
|
||||
1. Copy `templates/README.md.template` and `templates/CLAUDE.md.template`.
|
||||
2. `git init` immediately, even if the project is throwaway. Throwaway
|
||||
projects survive longer than you expect.
|
||||
3. First commit: scaffolding only, no real code. Makes future `git log`
|
||||
readable.
|
||||
4. Add the project to the workspace `README` (when we have one) so it's
|
||||
discoverable.
|
||||
|
||||
## What planning is *not*
|
||||
|
||||
- It's not Jira tickets. We don't need a board for two people.
|
||||
- It's not Gantt charts. If we need one, we're building the wrong thing.
|
||||
- It's not status theater. The Monday post is for spotting blocks, not
|
||||
for proving you worked.
|
||||
@@ -1,111 +0,0 @@
|
||||
# 05 — Code & deliverable style
|
||||
|
||||
Naming, comments, structure. Same rules apply whether a human or Claude
|
||||
typed the code.
|
||||
|
||||
## Naming
|
||||
|
||||
- **Files** — lowercase, hyphens for docs (`git-workflow.md`),
|
||||
underscores for Python (`task_runner.py`), kebab for JS/TS where the
|
||||
ecosystem prefers it. Match the surrounding project.
|
||||
- **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`,
|
||||
not `taskRunner`.
|
||||
- **Variables** — say what they are, not their type. `users`, not
|
||||
`userArray`. `retryCount`, not `n`.
|
||||
- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
|
||||
- **Constants** — `UPPER_SNAKE_CASE` only when truly module-level
|
||||
constants. Inside functions, just use a normal `const`.
|
||||
- **No abbreviations** unless they're a domain term. `database`, not
|
||||
`db`. `request`, not `req`. (`req`/`res` in Express handlers is fine —
|
||||
domain convention.)
|
||||
|
||||
## Comments
|
||||
|
||||
Default to none. A comment is justified when **all** are true:
|
||||
|
||||
- The *why* is non-obvious from the code.
|
||||
- A future reader would otherwise misread the code.
|
||||
- The code itself can't be made clearer (rename, extract, restructure).
|
||||
|
||||
Don't write:
|
||||
|
||||
- `// increment counter` next to `counter++`
|
||||
- `// added for the auth refactor` — belongs in the commit message
|
||||
- Block comments restating function signatures
|
||||
- TODOs without an owner or a date — they rot. Either fix it now, file
|
||||
an issue, or delete the comment.
|
||||
|
||||
Do write:
|
||||
|
||||
- One-liners explaining a non-obvious workaround, with the *why*.
|
||||
- A `# NOTE:` when behavior would surprise a reader.
|
||||
- Module headers only when a file does something the directory layout
|
||||
doesn't already explain.
|
||||
|
||||
## File structure
|
||||
|
||||
- One concept per file. If you can't summarize the file in one sentence,
|
||||
split it.
|
||||
- Keep tests next to the code, not in a parallel tree, unless the
|
||||
project already does the parallel tree.
|
||||
- Generated files go in `dist/`, `build/`, or similar — and into
|
||||
`.gitignore`. Never edit a generated file.
|
||||
- Lockfiles are checked in. Always.
|
||||
|
||||
## Errors
|
||||
|
||||
- Fail loudly at boundaries (user input, external APIs, file I/O).
|
||||
- Don't `try/except` to silence errors. If you catch, you handle.
|
||||
- Internal functions trust their callers. Don't validate the same input
|
||||
three layers deep.
|
||||
- Logged errors include enough context to debug from logs alone — what
|
||||
was being attempted, which inputs, which path.
|
||||
|
||||
## Tests
|
||||
|
||||
- Test the behavior, not the implementation. If a refactor that
|
||||
preserves behavior breaks a test, the test was wrong.
|
||||
- One assertion per test, ideally. "Tests that test many things at once
|
||||
fail unhelpfully."
|
||||
- Fixtures live next to the tests that use them.
|
||||
- Slow / flaky tests get marked or quarantined, not silently retried.
|
||||
- New code without a test is incomplete unless the project genuinely
|
||||
has no test infrastructure (rare, and a bug in itself).
|
||||
|
||||
## READMEs
|
||||
|
||||
Every repo has a `README.md`. It answers, in order:
|
||||
|
||||
1. **What is this?** One paragraph.
|
||||
2. **How do I run it?** Bash blocks for setup, run, test.
|
||||
3. **How do I develop on it?** Where the code lives, what the conventions
|
||||
are.
|
||||
4. **Where does the data come from / go to?** Only if non-obvious.
|
||||
5. **Pointers.** Related repos, dashboards, docs.
|
||||
|
||||
Use `templates/README.md.template`. If the README is shorter than the
|
||||
template, that's fine — delete the unused sections.
|
||||
|
||||
## Deliverables (task packages, datasets, exports)
|
||||
|
||||
When we ship a deliverable to a partner or downstream consumer:
|
||||
|
||||
1. Versioned filename: `<name>-v<n>.<ext>` or `<name>-<YYYYMMDD>.<ext>`.
|
||||
Pick one convention per project and stick to it.
|
||||
2. Ships with a `README` describing schema, generation date, known
|
||||
limitations.
|
||||
3. Ships with a verification report (counts, checksums, sanity checks)
|
||||
in the same archive.
|
||||
4. Exact commit hash that produced it goes in the README.
|
||||
|
||||
See `docs/06-handoff.md` for the full checklist.
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- Don't introduce a third way to do something we already do two ways.
|
||||
Pick one and migrate.
|
||||
- Don't add config options "for flexibility" without a real use case.
|
||||
YAGNI.
|
||||
- Don't refactor unrelated code in a feature PR. Open a separate PR.
|
||||
- Don't optimize before measuring. "It might be slow" is not a
|
||||
measurement.
|
||||
@@ -1,121 +0,0 @@
|
||||
# 06 — Handoff
|
||||
|
||||
Task packages, deliverables, and how we hand work between team members
|
||||
or to external consumers.
|
||||
|
||||
## Why this matters
|
||||
|
||||
Handoff failures cost more than the original work. A package that's
|
||||
"obviously how it works" to the author is a half-day of confusion for
|
||||
the recipient. Treat handoff as part of the deliverable, not as
|
||||
afterthought packaging.
|
||||
|
||||
## Two kinds of handoff
|
||||
|
||||
1. **Internal** — passing work to another team member (or future-you).
|
||||
Usually a branch, a PR, or a half-finished prototype.
|
||||
2. **External** — shipping a versioned artifact to a partner, customer,
|
||||
or downstream pipeline. Usually a zip, a dataset, or a release.
|
||||
|
||||
Both use the checklist in `templates/HANDOFF_CHECKLIST.template.md`. The
|
||||
external case has a higher bar.
|
||||
|
||||
## Task packages
|
||||
|
||||
When we ship a task package (e.g. `praxis-sample-5.zip`,
|
||||
`task-assistant-v0.2-handoff-*.zip`), it must contain:
|
||||
|
||||
```
|
||||
<package>/
|
||||
├── README.md ← what this is, who it's for, how to use it
|
||||
├── CHANGELOG.md ← what changed since the last version
|
||||
├── VERIFICATION.md ← counts, checksums, sanity checks
|
||||
├── manifest.json ← machine-readable metadata
|
||||
├── data/ ← the actual deliverable
|
||||
└── scripts/ ← only what's needed to use the package
|
||||
```
|
||||
|
||||
`manifest.json` minimum fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "praxis-sample-5",
|
||||
"version": "0.5.0",
|
||||
"generated_at": "2026-05-18T17:00:00Z",
|
||||
"source_commit": "<full sha>",
|
||||
"source_repo": "<git remote url>",
|
||||
"record_count": 1234,
|
||||
"schema_version": "1.0"
|
||||
}
|
||||
```
|
||||
|
||||
If you can't fill a field, leave it as `null` and explain in the README.
|
||||
Never make one up.
|
||||
|
||||
## Internal handoff (branch / PR)
|
||||
|
||||
Before handing off:
|
||||
|
||||
- PR description is current. The summary describes what shipped, not
|
||||
what was attempted.
|
||||
- The "test plan" section in the PR template is filled in honestly. If
|
||||
you didn't test something, say so — don't bury it.
|
||||
- Any AI-assisted decisions that surprised you go in a `## Notes for
|
||||
reviewer` section. "Claude tried X first, that didn't work because Y,
|
||||
here's the working approach" saves the reviewer a re-derivation.
|
||||
- Local-only state (env vars, scratch data) is documented or scripted.
|
||||
"Works on my machine" is not a handoff.
|
||||
|
||||
The recipient should be able to:
|
||||
|
||||
1. `git checkout` the branch
|
||||
2. Read the PR description
|
||||
3. Run the test plan
|
||||
4. Form an opinion
|
||||
|
||||
— without messaging you. If they have to message you, the handoff is
|
||||
incomplete.
|
||||
|
||||
## External handoff (versioned artifact)
|
||||
|
||||
Higher bar. In addition to the task package contents above:
|
||||
|
||||
- **Reproducibility.** Someone with access to the source repo can
|
||||
rebuild the artifact from the commit hash in `manifest.json`. Test
|
||||
this at least once before the first release.
|
||||
- **Verification report.** A machine-checkable report (JSON or
|
||||
similar) showing the artifact passed our pre-ship checks. Include
|
||||
what was checked and the result.
|
||||
- **Provenance.** If the artifact was generated using AI assistance,
|
||||
note the model and any human-in-the-loop steps. Not for ceremony —
|
||||
for debugging when something looks wrong six months from now.
|
||||
- **License & attribution.** Even for internal partners. Be explicit
|
||||
about what they can and can't do with the data.
|
||||
|
||||
## What NOT to ship
|
||||
|
||||
- Files larger than ~500 MB without a conversation about delivery
|
||||
channel.
|
||||
- Anything containing real PII unless that was explicitly the deal.
|
||||
- `.env`, secrets, API keys, internal hostnames.
|
||||
- "Final final v3" filenames. Use the version field. If it's `final`,
|
||||
it's `v1.0`.
|
||||
- A package without a README. Even a one-line README beats none.
|
||||
|
||||
## Receiving a handoff
|
||||
|
||||
When you're on the receiving end:
|
||||
|
||||
1. Read the README first, fully. Resist the urge to start running
|
||||
scripts.
|
||||
2. Run the verification report. If it doesn't pass, stop and message
|
||||
the sender before doing anything else.
|
||||
3. Note any surprise — naming, missing files, version mismatch — and
|
||||
send it back to the sender within a day. Drift gets worse with
|
||||
silence.
|
||||
|
||||
## Templates
|
||||
|
||||
- `templates/HANDOFF_CHECKLIST.template.md` — fill out per handoff,
|
||||
ships in the package.
|
||||
- `templates/PR_DESCRIPTION.template.md` — for internal handoff via PR.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Team library
|
||||
|
||||
A small catalog of focused specs and reusable assets. Read the entries
|
||||
that match the current task; ignore the rest.
|
||||
|
||||
This directory is **not** the team's general working agreements — those
|
||||
live in [`../AGENTS.md`](../AGENTS.md). The library is for narrower,
|
||||
deeper specs that would bloat AGENTS.md if inlined.
|
||||
|
||||
## How to use this
|
||||
|
||||
When starting a non-trivial task:
|
||||
|
||||
1. Read [`../AGENTS.md`](../AGENTS.md) (general rules).
|
||||
2. Scan this catalog. If an entry matches your task, read its `SPEC.md`.
|
||||
3. If nothing matches, proceed.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Entry | Read it when… |
|
||||
| -------------------------------------- | ---------------------------------------------------------- |
|
||||
| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files |
|
||||
|
||||
(More entries will be added as the team encounters recurring questions
|
||||
worth standardizing.)
|
||||
|
||||
## Adding to the library
|
||||
|
||||
Promote a topic to a library entry when **all** are true:
|
||||
|
||||
1. The topic has bitten us at least twice.
|
||||
2. It's narrower than AGENTS.md general rules and would make AGENTS.md
|
||||
bloated to inline.
|
||||
3. Steps are stable enough to write down.
|
||||
|
||||
Layout for a new entry:
|
||||
|
||||
```
|
||||
library/<entry-name>/
|
||||
└── SPEC.md ← English, the actual spec
|
||||
```
|
||||
|
||||
`SPEC.md` follows the same editing rules as AGENTS.md (one rule per
|
||||
bullet, no emoji, examples beat prose, ~300 lines max). Lead with a
|
||||
**When to read this** section so agents can decide quickly whether the
|
||||
entry applies.
|
||||
|
||||
If a future entry needs scripts or skill packages, add them next to
|
||||
`SPEC.md`. The catalog table above gets a one-line "read it when…" for
|
||||
each new entry.
|
||||
@@ -0,0 +1,287 @@
|
||||
# git-upload — what to commit, what not to
|
||||
|
||||
## When to read this
|
||||
|
||||
- Pushing to a remote for the first time on a project.
|
||||
- Adding a new file type the project hasn't committed before (data
|
||||
dumps, generated artifacts, model weights, .env files, screenshots).
|
||||
- About to run `git add .` or `git add -A`.
|
||||
- Cleaning up a `.gitignore`.
|
||||
- Suspect or confirmed a secret was committed.
|
||||
|
||||
This is a focused spec, not the full Git workflow. Branch / commit /
|
||||
PR / tagging rules live in [`../../AGENTS.md`](../../AGENTS.md) §3.
|
||||
|
||||
## The first rule
|
||||
|
||||
`git status` and `git diff --cached` before every push. **Read every
|
||||
file name in the staging list.** Most accidents happen because the
|
||||
author didn't notice an extra file got staged.
|
||||
|
||||
## What goes in
|
||||
|
||||
Source and infrastructure for the project. Things that:
|
||||
|
||||
- Are written by humans (or AI under a human's review).
|
||||
- Are reasonably small (text or small binaries — a few MB at most).
|
||||
- Are the canonical version, not a derivative or cache.
|
||||
|
||||
Concretely:
|
||||
|
||||
- Source code, scripts, tests
|
||||
- Configuration **templates** (e.g. `.env.example`) — never real values
|
||||
- Schemas, fixtures, small reference datasets that are part of the project
|
||||
- Documentation (Markdown, small images for docs)
|
||||
- Lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, etc.) —
|
||||
always commit these
|
||||
- Build / CI configuration
|
||||
- License, README, CHANGELOG
|
||||
|
||||
## What stays out
|
||||
|
||||
### Secrets and credentials
|
||||
|
||||
**Never commit any of these, even once, even temporarily.**
|
||||
|
||||
- API keys, tokens, passwords (any provider)
|
||||
- `.env`, `.env.local`, `.env.production`, `*.pem`, `*.key`, `id_rsa`,
|
||||
`*.pfx`, `*.p12`
|
||||
- OAuth client secrets, webhook signing keys
|
||||
- Database connection strings with embedded passwords
|
||||
- Cloud credentials (`~/.aws/credentials`, service account JSON)
|
||||
- Personal access tokens in URLs (`https://user:TOKEN@host/repo.git`)
|
||||
- Cookies, session tokens, signed JWTs from real users
|
||||
|
||||
A "delete the secret" commit later is **not enough** — the secret stays
|
||||
in history. See [Recovering from a leaked secret](#recovering-from-a-leaked-secret).
|
||||
|
||||
### Generated and runtime files
|
||||
|
||||
These are derivatives — regenerable from sources, not source themselves.
|
||||
|
||||
```
|
||||
# Build outputs
|
||||
dist/ build/ out/ target/ .next/ .nuxt/
|
||||
|
||||
# Dependency caches
|
||||
node_modules/ .venv/ venv/ __pycache__/ .pytest_cache/ .mypy_cache/
|
||||
.tox/ .gradle/ vendor/ Pods/
|
||||
|
||||
# Editor / IDE state
|
||||
.vscode/ .idea/ *.swp .DS_Store Thumbs.db desktop.ini
|
||||
|
||||
# Local runtime / logs
|
||||
logs/ *.log tmp/ .cache/ runtime-temp/ feedback-records/
|
||||
generated_*/ reports/
|
||||
```
|
||||
|
||||
The exception: vendored dependencies that you **deliberately** want
|
||||
under version control (offline / air-gapped builds). That's a project
|
||||
decision documented in the project's AGENTS.md, not the default.
|
||||
|
||||
### Large binaries
|
||||
|
||||
> 5 MB → stop. Talk about Git LFS or out-of-band storage first.
|
||||
|
||||
Common offenders to scan for before pushing:
|
||||
|
||||
- Model weights (`.bin`, `.safetensors`, `.gguf`, `.ckpt`, `.pt`, `.onnx`)
|
||||
- Datasets (`.parquet`, `.arrow`, `.zip`, `.tar.gz`, `.7z` over a few MB)
|
||||
- Videos, raw images, audio
|
||||
- Database dumps, full backups
|
||||
- Vendor SDK installers
|
||||
|
||||
Once a large binary is in history, the repo is bloated forever (unless
|
||||
you rewrite history). Catch it before push, not after.
|
||||
|
||||
### Personal / machine-specific files
|
||||
|
||||
- Personal editor settings — those go in `~/.<editor>` not the repo
|
||||
- Agent personal config — `.claude/settings.local.json`,
|
||||
`~/.codex/config.toml` (the personal one)
|
||||
- Per-machine paths, hostnames, debug toggles
|
||||
- Temporary scratch files, half-written notes
|
||||
|
||||
### User and customer data
|
||||
|
||||
- Real PII (names, emails, phone numbers from real people)
|
||||
- Real internal records, customer logs, support tickets
|
||||
- Anything covered by NDA or compliance scope
|
||||
|
||||
If sample data is needed for tests, generate it synthetically or use
|
||||
public fixtures.
|
||||
|
||||
## .gitignore patterns
|
||||
|
||||
A baseline for most projects (adapt to the language):
|
||||
|
||||
```gitignore
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
desktop.ini
|
||||
|
||||
# Editors
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*~
|
||||
|
||||
# Secrets
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
*.pem
|
||||
*.key
|
||||
id_rsa*
|
||||
*.pfx
|
||||
*.p12
|
||||
|
||||
# Agent local state
|
||||
.claude/settings.local.json
|
||||
.claude/projects/
|
||||
.claude/sessions/
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
.pytest_cache/
|
||||
.mypy_cache/
|
||||
|
||||
# Node
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-error.log
|
||||
|
||||
# Build outputs (uncomment what applies)
|
||||
# dist/
|
||||
# build/
|
||||
# out/
|
||||
|
||||
# Logs / temp
|
||||
*.log
|
||||
tmp/
|
||||
.cache/
|
||||
```
|
||||
|
||||
Two rules for `.gitignore`:
|
||||
|
||||
1. **Be deliberate about negations** (`!.env.example` etc.) — they
|
||||
override broader rules and are the source of "why isn't this file
|
||||
ignored" confusion.
|
||||
2. **`.gitignore` only ignores untracked files.** A file already in the
|
||||
index keeps being tracked even if you add it to `.gitignore`. To
|
||||
actually stop tracking it: `git rm --cached <file>` then commit.
|
||||
|
||||
## Staging discipline
|
||||
|
||||
`git add .` and `git add -A` are dangerous when there are unrecognized
|
||||
untracked files. The safe pattern:
|
||||
|
||||
```bash
|
||||
git status --short # see what's changed
|
||||
git add <specific files> # stage by name
|
||||
git diff --cached # read what's actually being committed
|
||||
git commit -m "..."
|
||||
```
|
||||
|
||||
If you have many related files and want to use a glob, prefer `git add
|
||||
src/foo/` (a directory) over `git add .` (the world).
|
||||
|
||||
## Sensitive-info scan
|
||||
|
||||
Before push, especially when you've added new files:
|
||||
|
||||
```bash
|
||||
git diff --cached
|
||||
```
|
||||
|
||||
For periodic / pre-release scans across the working tree:
|
||||
|
||||
```bash
|
||||
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
|
||||
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
|
||||
```
|
||||
|
||||
Hits need **human judgment** — demo keys in comments and real keys both
|
||||
match the same regex. Don't blind-commit and don't blind-delete.
|
||||
|
||||
For a stronger sweep, use a dedicated tool (`gitleaks`, `trufflehog`,
|
||||
or your platform's secret scanning). They have richer rule sets than
|
||||
the regex above. Run them at least before any first-time push to a new
|
||||
remote.
|
||||
|
||||
## Recovering from a leaked secret
|
||||
|
||||
When a real secret has been committed (and possibly pushed):
|
||||
|
||||
1. **Invalidate the secret immediately.** Rotate the key/token at the
|
||||
provider before doing anything else. This is the only step that
|
||||
actually makes the leak safe — everything below is cleanup.
|
||||
2. Replace the secret locally. Move it to `.env` (which is gitignored)
|
||||
or your secrets manager.
|
||||
3. Notify collaborators. They need to know not to base work on the
|
||||
compromised commit until history is rewritten.
|
||||
4. Decide whether to rewrite history. For a public repo or one with a
|
||||
short history, use `git filter-repo` (preferred over the deprecated
|
||||
`filter-branch`) or your platform's secret-removal tooling. After
|
||||
rewrite, force-push with team agreement and ask everyone to re-clone.
|
||||
5. Document the incident briefly — what leaked, when, how, what was
|
||||
done. Future-you will want this when a similar mistake happens.
|
||||
|
||||
A "delete the key" commit on top is **not safe**. The secret is still
|
||||
in history and accessible to anyone who clones.
|
||||
|
||||
## URLs with embedded credentials
|
||||
|
||||
A common slip: pushing with a token-embedded URL writes the token into
|
||||
`.git/config`:
|
||||
|
||||
```
|
||||
remote "origin"
|
||||
url = https://user:TOKEN@host/owner/repo.git
|
||||
```
|
||||
|
||||
Fix: after pushing, reset the URL to the credential-free form and let
|
||||
the credential helper handle auth:
|
||||
|
||||
```bash
|
||||
git remote set-url origin https://host/owner/repo.git
|
||||
```
|
||||
|
||||
Verify with `git remote -v`. The token also lives in shell history and
|
||||
in any `.bash_history` / PowerShell history file — clear it if the
|
||||
token is sensitive enough to warrant rotation.
|
||||
|
||||
## First push to a new remote
|
||||
|
||||
A short checklist when initializing a project:
|
||||
|
||||
- [ ] `.gitignore` covers secrets, build outputs, editor state, agent
|
||||
local state
|
||||
- [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree
|
||||
- [ ] No files >5 MB in the tree (check with `find . -size +5M
|
||||
-not -path "./.git/*"` or equivalent)
|
||||
- [ ] `git status` shows only files you mean to commit
|
||||
- [ ] `git diff --cached` reads cleanly — no surprise content
|
||||
- [ ] Repo URL on the remote matches the one you intend; no token in
|
||||
the URL
|
||||
- [ ] Credential helper is configured (so you don't have to embed tokens
|
||||
in URLs)
|
||||
|
||||
After first push: `git remote -v` should show a clean URL.
|
||||
|
||||
## Don'ts (summary)
|
||||
|
||||
- Don't `git add .` with unrecognized untracked files in the tree.
|
||||
- Don't commit `.env`, secrets, tokens, or real credentials — ever, not
|
||||
even temporarily.
|
||||
- Don't commit large binaries (>5 MB) without a Git LFS conversation.
|
||||
- Don't commit generated / cache directories.
|
||||
- Don't commit real user data or PII.
|
||||
- Don't try to "clean up" a leaked secret with a delete commit. Rotate
|
||||
first, rewrite history if needed.
|
||||
- Don't leave tokens in `.git/config` after a token-in-URL push.
|
||||
- Don't `--no-verify` to skip pre-commit secret scans.
|
||||
@@ -1,53 +0,0 @@
|
||||
# CLAUDE.md — <project name>
|
||||
|
||||
<!--
|
||||
Template. Copy into a new repo and fill the bracketed sections.
|
||||
Delete sections that don't apply. Keep total length under ~100 lines.
|
||||
-->
|
||||
|
||||
## What this project is
|
||||
|
||||
<One or two sentences. What does it do, who is it for.>
|
||||
|
||||
## Run it
|
||||
|
||||
```bash
|
||||
# install
|
||||
<command>
|
||||
|
||||
# run
|
||||
<command>
|
||||
|
||||
# test
|
||||
<command>
|
||||
|
||||
# lint / typecheck
|
||||
<command>
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
<One paragraph. Where are the entry points, how does data flow, what
|
||||
are the major modules. Skip diagrams unless they save words.>
|
||||
|
||||
Key files:
|
||||
|
||||
- `<path>` — <one-line role>
|
||||
- `<path>` — <one-line role>
|
||||
|
||||
## Conventions specific to this repo
|
||||
|
||||
<Anything that's not obvious from reading the code. Naming patterns,
|
||||
where to add new features, what's auto-generated, etc.>
|
||||
|
||||
## Don'ts
|
||||
|
||||
<Things Claude or a new contributor has gotten wrong before.
|
||||
One line each. Add to this list as you discover them.>
|
||||
|
||||
- Don't <…>
|
||||
- Don't <…>
|
||||
|
||||
## External resources
|
||||
|
||||
<Links to dashboards, related repos, docs, ticket trackers.>
|
||||
@@ -1,71 +0,0 @@
|
||||
# Handoff checklist — <package or branch name>
|
||||
|
||||
<!--
|
||||
Fill this out before declaring the handoff complete.
|
||||
Ships inside the package for external handoffs.
|
||||
Lives in the PR description for internal handoffs.
|
||||
-->
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: <package or branch name>
|
||||
- **Version**: <e.g. v0.5.0 or commit sha>
|
||||
- **Generated at**: <ISO timestamp>
|
||||
- **Source repo**: <url>
|
||||
- **Source commit**: <full sha>
|
||||
- **Author / handoff owner**: <name>
|
||||
- **Recipient**: <name or team>
|
||||
|
||||
## Contents
|
||||
|
||||
- [ ] `README.md` — describes what this is, how to use it
|
||||
- [ ] `CHANGELOG.md` — what's different from the previous version (or
|
||||
"first release")
|
||||
- [ ] `manifest.json` — machine-readable metadata, all fields filled or
|
||||
explicitly null
|
||||
- [ ] `VERIFICATION.md` — what we checked, what passed
|
||||
- [ ] Data / artifacts — the actual deliverable
|
||||
- [ ] Scripts — only what's needed to use the package
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] Record / file counts match expected
|
||||
- [ ] Checksums computed and recorded
|
||||
- [ ] Sanity checks pass (list them)
|
||||
- [ ] No secrets, `.env`, or credentials included
|
||||
- [ ] No PII unless explicitly part of the deliverable
|
||||
- [ ] Total size reasonable for delivery channel
|
||||
|
||||
Verification report path: `<path>`
|
||||
|
||||
## Reproducibility
|
||||
|
||||
- [ ] Confirmed someone with repo access can rebuild from
|
||||
`source_commit` (note who tested this and when)
|
||||
- [ ] Build / generation command documented in `README.md`
|
||||
- [ ] External dependencies pinned to versions
|
||||
|
||||
## Provenance (if AI-assisted)
|
||||
|
||||
- Model used: <e.g. claude-opus-4-7>
|
||||
- Human-in-the-loop steps: <which parts a human reviewed / approved>
|
||||
- Notable AI-assisted decisions: <anything that would matter if the
|
||||
output looks wrong six months from now>
|
||||
|
||||
## Known limitations
|
||||
|
||||
<Things that don't work, edge cases that aren't covered, follow-ups
|
||||
that didn't make this version. Be specific. "Works on my machine" is
|
||||
not a limitation, it's a problem to fix before shipping.>
|
||||
|
||||
- <…>
|
||||
- <…>
|
||||
|
||||
## Recipient instructions
|
||||
|
||||
- [ ] Read `README.md` first
|
||||
- [ ] Run the verification report — if it fails, stop and contact the
|
||||
sender
|
||||
- [ ] Confirm receipt within <X days>
|
||||
- [ ] Report any surprises (missing files, version mismatch, naming)
|
||||
back to the sender within <X days>
|
||||
@@ -1,52 +0,0 @@
|
||||
<!--
|
||||
PR description template. Title goes in the PR title field, not here.
|
||||
Title format: <area>: <imperative summary under 70 chars>
|
||||
-->
|
||||
|
||||
## Summary
|
||||
|
||||
<One sentence describing what this PR does. Then 1–3 bullets if needed.>
|
||||
|
||||
- <bullet>
|
||||
- <bullet>
|
||||
|
||||
## Why
|
||||
|
||||
<The motivation. What problem does this solve, what decision does it
|
||||
implement, what bug does it fix. If this links to an issue or earlier
|
||||
discussion, link it here.>
|
||||
|
||||
## What changed
|
||||
|
||||
<Bulleted list of the actual changes, grouped by area if it spans
|
||||
multiple. Keep it factual — the diff is the source of truth, this is
|
||||
just a map.>
|
||||
|
||||
- `<file or area>` — <change>
|
||||
- `<file or area>` — <change>
|
||||
|
||||
## Test plan
|
||||
|
||||
<Bulleted checklist. Mark `[x]` for done, `[ ]` for didn't do (and
|
||||
explain why below). Be honest — "didn't test" is acceptable, "claimed
|
||||
tested but didn't" is not.>
|
||||
|
||||
- [ ] Unit tests pass locally (`<command>`)
|
||||
- [ ] Lint / typecheck pass (`<command>`)
|
||||
- [ ] <feature-specific check>
|
||||
- [ ] <feature-specific check>
|
||||
|
||||
## Out of scope
|
||||
|
||||
<Things you noticed but explicitly chose not to fix in this PR. Helps
|
||||
reviewers not bring them up.>
|
||||
|
||||
## Notes for reviewer
|
||||
|
||||
<Anything that surprised you, AI-assisted decisions worth flagging,
|
||||
shortcuts taken, or "I considered X but went with Y because Z". Skip
|
||||
this section if there's nothing notable.>
|
||||
|
||||
---
|
||||
|
||||
🤖 AI-assisted with Claude Code.
|
||||
@@ -1,62 +0,0 @@
|
||||
# <project name>
|
||||
|
||||
<One sentence. What this is, in plain language.>
|
||||
|
||||
## What it does
|
||||
|
||||
<One paragraph. Slightly more detail than the tagline. Who would use
|
||||
it, what problem it solves, what it explicitly does not do.>
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# clone
|
||||
git clone <url>
|
||||
cd <repo>
|
||||
|
||||
# install
|
||||
<command>
|
||||
|
||||
# run
|
||||
<command>
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```
|
||||
<a few lines of what the user should see>
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# tests
|
||||
<command>
|
||||
|
||||
# lint / typecheck
|
||||
<command>
|
||||
|
||||
# format
|
||||
<command>
|
||||
```
|
||||
|
||||
Code lives in `<dir>`. Tests live in `<dir>`. See [docs/](docs/) for
|
||||
deeper architecture notes (or delete this line if there are none).
|
||||
|
||||
## Configuration
|
||||
|
||||
<Env vars, config files, secrets. Point to a `.env.example` if there is
|
||||
one. Don't list real values.>
|
||||
|
||||
## Data sources / outputs
|
||||
|
||||
<Only if non-obvious. Where does input come from, where do outputs go.>
|
||||
|
||||
## Related
|
||||
|
||||
- <link>
|
||||
- <link>
|
||||
|
||||
## License
|
||||
|
||||
<Internal / MIT / etc.>
|
||||
Reference in new issue
Block a user