Customization Guide

Customization Guide

How to tailor ai-coding-ok to your project's specific needs. What you can change, what you shouldn't, and how to do it safely.

---

What can be customized

✅ Safe to modify

File	What to customize	When
project-memory.md	Project facts, architecture, constraints, known issues	Whenever facts change
decisions-log.md	Add new ADRs for your decisions	Whenever you make an architecture decision
task-history.md	(AI manages this automatically)	N/A
coding-standards.md	Language-specific conventions, linting rules, naming	During initial setup
workflows.md	Add project-specific workflow scenarios	When your process differs from defaults
system-prompt.md	Agent persona, role definitions	Rarely — only for significant project culture

⚠️ Modify with caution

File	Caution
AGENTS.md	Keep the PDCA mandate block at the top. Architecture section below can be customized.
copilot-instructions.md	Keep the PDCA enforcement block and mandatory output format. Add project-specific rules below.
CLAUDE.md	Keep the STOP instruction and @AGENTS.md import.

❌ Don't modify

File	Reason
SKILL.md (in the ai-coding-ok repo)	This is the framework source — changes here affect all projects
Template files (templates/en/, templates/zh/)	These are the product source — modify behavior there, not in installed files
Version markers (<!-- ai-coding-ok: vX.Y -->)	These are used by the Upgrade system

---

Customizing project-memory.md

This is the most commonly customized file. Here's how to keep it useful:

Adding a new constraint

## ⚠️ Key Constraints

1. Never push to git without explicit user request
2. All API endpoints must have input validation
3. **All monetary values must use Decimal, never float** ← add project-specific constraint

Adding a known issue

## 🐛 Known Issues & Common Pitfalls

| # | Issue | Solution | Date |
|---|-------|----------|------|
| 1 | SQLite locks during concurrent writes | Use WAL mode (see ADR-006) | 2026-07-14 |

Updating architecture

When you add a new module, update the architecture section:

## 📦 Core Modules

| Module | Description | Status |
|--------|-------------|--------|
| api/products.py | Product CRUD + search | ✅ Done |
| api/orders.py | Order management | 🔨 In Progress |
| services/payment.py | Payment gateway integration | 📋 Planned |

Rotating stale content

If project-memory.md exceeds 500 lines:

1. Move old "Known Issues" that are permanently resolved to a docs/ file
2. Move deprecated architecture decisions to decisions-log.md as deprecated ADRs
3. Archive old module descriptions for removed features

---

Customizing coding-standards.md

Language-specific conventions

Replace the default Python conventions with your language:

Python project:

## Code Style
- Follow PEP 8
- Use `from __future__ import annotations`
- Type hints on all public functions
- Docstrings: Google style

JavaScript/TypeScript project:

## Code Style
- Follow StandardJS
- Prettier for formatting
- ESLint with recommended rules
- JSDoc on all exports

Go project:

## Code Style
- Follow Effective Go
- `gofmt` + `goimports`
- Table-driven tests
- Errors returned, never panic in library code

---

Customizing workflows.md

Adding a project-specific workflow

## Database Migration

1. Create migration file in `migrations/`
2. Test migration forward AND backward
3. Run against a copy of production data
4. Update `project-memory.md` if schema docs changed
5. ⚠️ Update `task-history.md` with migration summary

Modifying the Feature workflow

If your team uses a different branch strategy, update the Feature workflow:

## Feature Development

1. Create branch: `feature/TASK-XXX-description`  ← adjust branch naming
2. Write tests first (TDD)
3. Implement
4. Open PR against `develop` (not `main`)  ← adjust target branch
5. ⚠️ Update memory files (Act phase)

---

Customizing for different project types

Web application

# In project-memory.md
## Tech Stack
- Frontend: React 18 + TypeScript + TailwindCSS
- Backend: Python 3.12 + FastAPI
- Database: PostgreSQL 16
- Cache: Redis
- Testing: Jest (frontend), pytest (backend)

CLI tool

# In project-memory.md
## Tech Stack
- Language: Go 1.22
- CLI framework: Cobra
- Config: Viper
- Testing: standard library + testify

Data pipeline

# In project-memory.md
## Tech Stack
- Orchestration: Airflow
- Processing: Python 3.12 + Pandas
- Storage: S3 + Parquet
- Testing: pytest + Great Expectations

---

Customizing the agent persona

Edit system-prompt.md to adjust the AI's behavior:

## Agent Persona

You are a **senior backend engineer** specializing in:
- REST API design
- Database optimization
- System reliability

Your default communication style is:
- Concise, data-driven
- Prefer code examples over prose
- Flag performance concerns proactively

---

Testing your customizations

After making changes, verify the framework still works:

# Check for broken references
bash scripts/verify.sh

# Manually test: ask the AI a question
# "What's our tech stack?" → should answer from project-memory.md
# "What was the last task?" → should answer from task-history.md

---

Customization anti-patterns

❌ Don't remove the PDCA mandate blocks

<!-- BAD: Don't delete this -->
## ⚠️ AI Agent 必读规范（每次任务必须执行）

Removing this defeats the entire purpose of ai-coding-ok.

❌ Don't hand-edit template placeholders

<!-- BAD: Don't leave {{placeholders}} or fill them manually -->
{{project-name}}  ← Let AI fill this during install

❌ Don't add project secrets to memory files

<!-- BAD: Memory files are committed to git -->
API_KEY=sk-abc123  ← Never put secrets here

Use environment variables or a .env file (gitignored) instead.

---

Next steps

• Upgrade ai-coding-ok — how upgrades preserve your customizations
• Template System — understand the template architecture
• Team Best Practices — standardizing customizations across a team