A minimalist repository template for Agent-collaborative development. Humans set direction, Agents execute. Rules, knowledge, and change records are all versioned.
The template itself ships without scripts or a Makefile — this is an AI collaboration template, and all files are created by the Agent following the guidance.
Two modes
- The user explicitly mentions the
harness-init、harnesstemplate, or asks to create a project following this template → Initialization mode - The current repository is already a
harness-initstructure → Collaboration mode - For a plain "create project", "initialize repository", or "build a skeleton", do not trigger; treat it as a normal project
Initialization mode
Create an Agent-first project skeleton from scratch.
Step 1: Confirm basic information
Confirm with the user:
- Project name (required)
- Project type (required, e.g., Web/API, frontend-backend separation, desktop, CLI/tool, library/SDK)
- Whether a frontend interface or other specialized constraints are needed
Step 2: Create the directory structure
<project>/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── CODEOWNERS
├── LICENSE
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .markdownlint.json
└── docs/
├── ARCHITECTURE.md
├── HISTORY_GUIDE.md
├── PLANS_GUIDE.md
├── REPO_COLLAB_GUIDE.md
├── exec-plans/
│ ├── README.md
│ ├── tech-debt-tracker.md
│ ├── active/ # 空目录,放 .gitkeep
│ ├── completed/ # 空目录,放 .gitkeep
│ └── templates/
│ └── execution-plan.md
└── histories/
└── template.md
Only the 4 "soul" documents plus ARCHITECTURE to guard the architecture. Other topic documents (SECURITY, RELIABILITY, CICD, FRONTEND, etc.) are added on demand once the real project takes shape; do not lay down placeholders during initialization.
Step 3: Instantiate key documents according to project type
Do not just perform template name substitution. You must turn these documents into project-specific content:
README.md: real project introduction, startup method, directory structureAGENTS.md: retain the navigation role, and clarify this project's most critical plan / history constraintsdocs/ARCHITECTURE.md: real module boundaries, runtime topology, data flow
Add on demand (not in the default skeleton; add after the project takes shape):
- Web / API / backend services →
docs/RELIABILITY.md、docs/SECURITY.md、docs/CICD.md - Frontend-backend separation / includes frontend →
docs/FRONTEND.md、docs/RELIABILITY.md、docs/CICD.md - Desktop / client →
docs/DESIGN.md、docs/RELIABILITY.md、docs/SECURITY.md - CLI / SDK / library →
docs/DESIGN.md、docs/CICD.md
If the project type is still unclear, do not pretend initialization is complete; first clarify the project type, then decide whether to add these documents.
Step 4: Generate file contents
Read references/init-files.md to obtain the full content of each file. When generating, note:
- Replace
{{PROJECT}}with the project name - All documents use Chinese
- Line endings LF
.editorconfig: UTF-8, 2-space indentation- Documents determined in Step 3 to be instantiated must be written as project-specific content, with no template placeholders left
references/init-files.mdonly provides the full content of the default slim skeleton; optional topic documents added according to project type must be newly written based on real project facts — do not pretend that the template already contains full content for them
Step 5: Manually verify the skeleton
Against the structure checklist from Step 2, confirm:
- All 4 soul documents (AGENTS.md + REPO_COLLAB_GUIDE.md + HISTORY_GUIDE.md + PLANS_GUIDE.md) are present
- ARCHITECTURE.md has been instantiated with project content
docs/exec-plans/The 3 subdirectories underdocs/histories/template.mdexists- Infrastructure files (.gitignore, .editorconfig, etc.) are present
Step 6: Tell the user the next steps
- Confirm that the three documents README, AGENTS, and ARCHITECTURE have been instantiated
- Replace the placeholder team name in
CODEOWNERSplaceholder team name in - Create as needed
apps/、packages/、infra/to hold real code - After real business is integrated, supplement according to project type
docs/SECURITY.mdand other topic documents
Collaboration Mode
Conventions to follow when working in a repository that already has the harness-init structure.
Must-read at the start of each task round
Read in order to build context:
AGENTS.md— navigation entry (routing only, no rules)docs/REPO_COLLAB_GUIDE.md— collaboration conventionsdocs/ARCHITECTURE.md— architecture overview
Must-read before code changes are complete
docs/HISTORY_GUIDE.md — when to record history, how to name it, how to redact it
Read selectively as tasks require
| Scenario | Document |
|---|---|
| Complex multi-step tasks | docs/PLANS_GUIDE.md |
| Topic documents extended by the project itself | See the files that exist at that time under docs/ files that existed at that time under |
Core Work Rules
- Land knowledge in the repository: important information that exists only in chat logs and in your head is as good as nonexistent
- Keep documents in sync: when behavior changes, update code, documents, and history in the same round
- Prefer simple solutions: choose simple, clear, observable solutions; do not pile on complexity
- When an Agent repeatedly fails: prioritize fixing the environment, fixing the guidance, and fixing the conventions; do not rely on prompts alone
- AGENTS.md does routing only: do not pile up rules; docs/ is the source of knowledge
- Do not depend on scripts: templates do not include Makefile/scripts; all files are created by the Agent according to the guidance
Complex Tasks: Create an Execution Plan
Trigger conditions (any one applies):
- The task spans multiple commits or work rounds
- Involves high-risk changes such as architecture, protocols, or data migration
- Requires phased verification, rollback strategy, or decision audit
- Multi-person or multi-Agent collaboration
Procedure:
- Copy
docs/exec-plans/templates/execution-plan.md - Name it
docs/exec-plans/active/YYYY-MM-DD-<slug>.md - Move it to when complete
docs/exec-plans/completed/
Read references/conventions.md to learn the detailed format of the execution plan.
After Repository Changes: Record Change History
Record every task that completes substantive repository changes:
- Copy
docs/histories/template.md - Create the directory
docs/histories/YYYY-MM/(if it does not exist) - Name it
YYYYMMDD-HHmm-<task-slug>.md
Content includes: user request (after redaction), main code/document changes, design intent, and key affected files.
No need to recordscenarios: pure Q&A/research tasks (no actual changes to repository content).
Confirm before committing
- Documents have been updated in sync
- Change history has been recorded
- Examples and documentation are consistent with the current implementation
Reference Files
references/init-files.md— all file contents required for initialization modereferences/conventions.md— detailed conventions, templates, and workflows for collaboration mode