企业官网建设流程全解析

Codebase Concerns

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

Analysis Date:[YYYY-MM-DD]

Tech Debt

Known Bugs

Security Considerations

Performance Bottlenecks

Fragile Areas

Scaling Limits

Dependencies at Risk

Missing Critical Features

Test Coverage Gaps

各板块字段定义如下，写作时必须逐项填全： | 板块 | 必填字段 | 字段语义 | |------|---------|---------| | Tech Debt | Issue / Why / Impact / Fix approach | 走捷径做了什么、为何如此、破坏了什么、如何正确修复 | | Known Bugs | Symptoms / Trigger / Workaround / Root cause / Blocked by | 现象、复现步骤、临时缓解、根因、是否被阻塞 | | Security Considerations | Risk / Current mitigation / Recommendations | 可能出什么错、现状防护、还应补什么 | | Performance Bottlenecks | Problem / Measurement / Cause / Improvement path | 什么慢、真实数值、为何慢、如何提速 | | Fragile Areas | Why fragile / Common failures / Safe modification / Test coverage | 为何易碎、典型故障、安全改法、测试覆盖 | | Scaling Limits | Current capacity / Limit / Symptoms at limit / Scaling path | 当前容量、何处崩溃、极限时表现、扩容路径 | | Dependencies at Risk | Risk / Impact / Migration plan | 废弃/无人维护/破坏性变更、失败影响、迁移方案 | | Missing Critical Features | Problem / Current workaround / Blocks / Implementation complexity | 缺什么、用户如何凑合、阻塞了什么、工作量量级 | | Test Coverage Gaps | What's not tested / Risk / Priority / Difficulty to test | 未测功能、潜在破坏、优先级、为何未测 | 文件尾部以审计日期收尾并声明其动态属性： ```markdown --- *Concerns audit: [date]* *Update as issues are fixed or new ones discovered*

2.1 源码侧的同构模板

gsd-codebase-mapper 代理 内部维护了一份 CONCERNS.md 的 concerns 焦点变体，字段略有精简（如 Tech Debt 用Files而非Why字段），但板块划分与主模板完全一致。这印证了模板在该系统中的双重存在：既供人工阅读，也作为 Agent 的直接产出格式。

三、完整填写示例：从占位符到真实条目

模板内置的 good_examples 段落 用一份虚构 SaaS 项目展示了每个板块的"正确写法"。以下提取关键条目作为范式参考（原文为英文，此处直译保留结构）：

Tech Debt 示例：

## Tech Debt **Database queries in React components:** - Issue: Direct Supabase queries in 15+ page components instead of server actions - Files: `app/dashboard/page.tsx`, `app/profile/page.tsx`, ... - Why: Rapid prototyping during MVP phase - Impact: Can't implement RLS properly, exposes DB structure to client - Fix approach: Move all queries to server actions in `app/actions/`, add proper RLS policies

Known Bugs 示例（必须含复现路径）：

**Race condition in subscription updates:** - Symptoms: User shows as "free" tier for 5-10 seconds after successful payment - Trigger: Fast navigation after Stripe checkout redirect, before webhook processes - Files: `app/checkout/success/page.tsx`, `app/api/webhooks/stripe/route.ts` - Workaround: Stripe webhook eventually updates status (self-heals) - Root cause: Webhook processing slower than user navigation, no optimistic UI update

Performance Bottlenecks 示例（强调真实测量值）：

**/api/courses endpoint:** - Problem: Fetching all courses with nested lessons and authors - File: `app/api/courses/route.ts` - Measurement: 1.2s p95 response time with 50+ courses - Cause: N+1 query pattern (separate query per course for lessons) - Improvement path: Use Prisma include to eager-load lessons, add Redis caching

Scaling Limits 示例（给出硬数字）：

**Supabase Free Tier:** - Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month - Limit: ~5000 users estimated before hitting limits - Symptoms at limit: 429 rate limit errors, DB writes fail - Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storage

Dependencies at Risk 示例：

**react-hot-toast:** - Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown - Impact: Toast notifications break, no graceful degradation - Migration plan: Switch to sonner (actively maintained, similar API)

这些示例的价值在于展示了统一的信息颗粒度：每条目都包含文件路径、可量化的测量值、具体的修复方向，绝不停留在情绪化评价。

四、填写指南：该放什么、不该放什么

模板末尾的 guidelines 段落 是最重要的写作纪律，直接决定文档质量。

4.1 应该收纳的内容（What belongs）

• 有明确影响与修复方案的技术债；
• 带复现步骤的已知 Bug；
• 安全缺口与缓解建议；
• 带测量数据的性能瓶颈；
• 容易改坏的脆弱代码；
• 带数字的扩展上限；
• 需要关注的依赖；
• 阻塞工作流的缺失功能；
• 测试覆盖缺口。

4.2 严禁收纳的内容（What does NOT belong）

• 无证据的观点（如 "code is messy"）；
• 只抱怨不给方案的诉苦（如 "auth sucks"）；
• 未来功能想法（归产品规划）；
• 普通 TODO（留在代码注释）；
• 运行良好的架构决策；
• 细微的代码风格问题。

4.3 填写纪律（When filling this template）

• Always include file paths—— 没有定位的担忧无法执行，路径用反引号包裹，如src/file.ts；
• Be specific with measurements—— 写 "500ms p95" 而非 "slow"；
• 每个 Bug 都要写复现步骤；
• 只提问题不行，要给出修复方向（"Suggest fix approaches, not just problems"）；
• 聚焦可执行条目；
• 按风险/影响排序；
• 问题解决后及时更新，发现新问题随时追加。

4.4 语气规范（Tone guidelines）

模板给出四组正反对照，核心是"专业、面向解决、聚焦风险、基于事实"：

• 专业而非情绪化："N+1 query pattern" 而非 "terrible queries"；
• 面向解决："Fix: add index" 而非 "needs fixing"；
• 聚焦风险："Could expose user data" 而非 "security is bad"；
• 基于事实："3.5s load time" 而非 "really slow"。

4.5 何时对阶段规划有用（Useful for phase planning when）

• 决定下一步做什么；
• 估算改动风险；
• 理解哪些地方要格外小心；
• 排定改进优先级；
• 为新 Claude 会话做上下文交接（onboarding）；
• 规划重构工作。

这份"风险即规划输入"的设计，正是 CONCERNS.md 与 GSD 规划流程衔接的关键接口。

五、这份文档如何被生成：源码级调用链

CONCERNS.md 不是手写孤本，而是 GSD 代码库测绘流水线的正式产物。理解其生成路径有助于你在新项目中复刻这套实践。

5.1 触发入口：map-codebase 与 scan

• map-codebase 工作流 会并行派出 4 个gsd-codebase-mapper子代理，其中 Agent 4 的焦点为concerns，明确指示"Analyze this codebase for technical debt, known issues, and areas of concern"，并写入 CONCERNS.md（Tech debt, bugs, security, performance, fragile areas）；
• scan 工作流 提供轻量路径，通过--focus concerns只派出单个 mapper 生成 CONCERNS.md，用于快速评估；
• 若运行时不支持Agent工具，map-codebase 会回退到顺序执行 4 轮内联测绘（sequential mapping），产出同样 7 份文档（见 map-codebase）。

5.2 concerns 焦点的探索命令

gsd-codebase-mapper 代理 为 concerns 焦点提供了三个侦察命令模板，可直接用于任何代码库：

# 1. 扫描 TODO/FIXME/HACK/XXX 标记 grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50 # 2. 按行数找出超大体量文件（潜在复杂度热点） find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -rn | head -20 # 3. 定位空返回值与桩代码 grep -rn "return null\|return \[\]\|return {}" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done